@reticlehq/server 3.9.0 → 3.10.0

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

@@ -13,7 +13,7 @@ import { aliasParam } from './args/alias-args.js';
 import { resolveSessionWithin } from '../../portal/session/timing/resolve-within.js';
 import { WALL_CLOCK } from '../../portal/session/timing/wall-clock.js';
 import { timeoutMsSchema } from './args/numeric-bounds.js';
-import { captureAct, captureVerdictedAct, pathOf, wroteSince } from '../../language/flows/replay.js';
+import { captureAct, captureVerdictedAct, pageOf, wroteSince } from '../../language/flows/replay.js';
 import { durableArg, durableOutput, reloadAndRecheck, withDurability } from './act/durable.js';
 import { ActionType, ActionWarning, ReticleCommand, CaptureLoss, DEFAULT_ASSERT_TIMEOUT_MS, InputMode, Verified, VerifiedReason, PredicateKind, checkIntent, } from '@reticlehq/core';
 import { leanActResult, mutatedWithin } from './act/act-view.js';
@@ -34,19 +34,19 @@ import { declaresState } from '@reticlehq/engine/question/predicate/predicate-as
 import { isStateUnwatched } from '@reticlehq/engine/evidence/blind-spots.js';
 import { hiddenMatchNote } from '@reticlehq/engine/evidence/already-true.js';
 import { inFlightRequestLabels, repeatedRequestLabels } from './act/settle-in-flight.js';
-import { awaitShownMatch, finishAfterMatch } from './act/after-match.js';
+import { awaitShownMatch, evaluateAfterAct, finishAfterMatch } from './act/after-match.js';
 import { noteProved } from './act/proved-controls.js';
-import { decideVerified } from '@reticlehq/engine/evidence/verified.js';
+import { decideVerified, withDeclinedDialog } from '@reticlehq/engine/evidence/verified.js';
 import { buildHonestyBlock, honestyForVerdict } from '@reticlehq/engine/evidence/honesty.js';
-import { declaredExpectations, declaresBodyIndependentChannel, } from '@reticlehq/engine/question/declared.js';
+import { declaredExpectations, declaresBodyIndependentChannel, namedReactions, provedConsequences, } from '@reticlehq/engine/question/declared.js';
 import { describeWaitTarget, namedNetIsInFlight } from '@reticlehq/engine/evidence/unsettled.js';
 import { saveFailedAssertCapsule } from './act-capsule.js';
 import { blastRadius, buildDivergenceCapsule, wireCapsule } from '../../judgement/capsule/capsule.js';
 import { predicateToExpectedLinks } from '@reticlehq/engine/question/predicate/predicate-to-links.js';
-import { absenceBlindSpotNote, buildCoverageStatement, blindSpotsFromState, transportGapNote, Coverage, impeachesCapture, } from '@reticlehq/engine/evidence/blind-spots.js';
+import { absenceBlindSpotNote, buildCoverageStatement, canvasPaintSpots, blindSpotsFromState, failingClauseReadsLostChannel, restsOnCompleteWindow, transportGapNote, Coverage, impeachesCapture, } from '@reticlehq/engine/evidence/blind-spots.js';
 import { acceptedWriteLabels } from '@reticlehq/engine/evidence/accepted-write.js';
 import { unreadWriteLabels, unreadWriteReason } from '@reticlehq/engine/evidence/unread-outcome.js';
-import { evaluatePredicate, waitForPredicate, provenExpectedLinks, PredicateSchema, } from '@reticlehq/engine/question/predicate/predicate.js';
+import { waitForPredicate, provenExpectedLinks, PredicateSchema, } from '@reticlehq/engine/question/predicate/predicate.js';
 import { sessionVerdictFacts } from '../../portal/session/session-verdict-facts.js';
 import { currentOf, healthEnvelope, refuseIfThrottled } from '../../portal/session/session-health.js';
 import { pausedShortCircuit, pausedOutputShape, withControl, PAUSED_NO_VERDICT, } from '../../portal/session/control-envelope.js';
@@ -54,14 +54,15 @@ import { asNumber, asRecord, asString } from '@reticlehq/core';
 import { sourceOf } from './tools-helpers.js';
 import { confirmedByDeclaration } from './act/act-danger.js';
 import { dispatchAct, preflightAct } from './act/act-preflight.js';
-import { actTargetNote, checkNet, followLostObservation } from './act/act-observation.js';
+import { actInconclusive, checkNet, followLostObservation, NAVIGATION_FOLLOW_GRACE_MS, } from './act/act-observation.js';
 import { intentArg, sessionIdShape } from './tool-kit.js';
+import { actCommand } from './act-command.js';
+import { tryRealInput } from './real-input-attempt.js';
 import { verdictIntentGap } from '@reticlehq/engine/evidence/verdict-intent-gap.js';
 import { asActionType, gradeOf } from './act/act-helpers.js';
 import { resolveActTarget } from './act/act-target.js';
+import { hiddenTargetField } from './act/resolve-target.js';
 import { screenRequestFindings, withAdvisories } from './act/screen-request.js';
-import { tryRealInput, rewriteUploadArgs, HOVER_NEEDS_POINTER_MSG } from './real-input-attempt.js';
-import { sessionRoot } from '../../memory/project/session-root.js';
 import { gradeOfPredicate } from './assert/assert-grade.js';
 import { readAlreadyTrue } from './act/already-true.js';
 import { engineBlindSpotsField, noteSourceSeen } from '../../portal/session/recorded-gaps.js';
@@ -71,45 +72,11 @@ import { engineBlindSpotsField, noteSourceSeen } from '../../portal/session/reco
  */
 const ACTION_TYPE_VALUES = Object.values(ActionType);
 const actionTypeEnum = z.enum(ACTION_TYPE_VALUES);
-/**
- * Single dispatch point for every ACT and ACT_SEQUENCE command.
- *
- * reticle_act, act_and_wait and act_sequence rewrite uploads here, once. The path resolves against
- * the session's project, not the daemon's folder, so a worktree uploads its own fixture (#1769).
- *
- * captureAct is called AFTER this, so the flow-recording captures the pre-rewrite args (the path
- * the agent actually wrote) rather than the base64 blob — replay would otherwise send 750 KiB of
- * base64 to the browser as if it were an inline content call.
- */
-export async function actCommand(deps, session, actArgs, timeoutMs) {
-    const rewritten = await rewriteUploadArgs({ fs: deps.fs, reticleRoot: sessionRoot(deps, session.id) }, 'string' === typeof actArgs['action'] ? actArgs['action'] : '', asRecord(actArgs['args']));
-    // Sequence and act_and_wait dispatch through here without the ACT handler's tryRealInput.
-    // A synthetic hover reports dispatched/settled while CSS :hover never applies — drive a real
-    // pointer when one is available, otherwise refuse rather than lie. A press on a lease takes its
-    // real keyboard, as reticle_act does: a synthetic Tab moves no focus.
-    const hover = ActionType.HOVER === actArgs['action'];
-    if (hover || (ActionType.PRESS === actArgs['action'] && deps.realInput === undefined)) {
-        const ref = asString(actArgs['ref']);
-        if (hover && ref === undefined)
-            throw new Error(HOVER_NEEDS_POINTER_MSG);
-        const action = hover ? ActionType.HOVER : ActionType.PRESS;
-        const real = await tryRealInput(deps, session, ref ?? '', action, actArgs);
-        if (hover && real.result === undefined)
-            throw new Error(HOVER_NEEDS_POINTER_MSG);
-        if (real.result !== undefined) {
-            const result = { dispatched: true, settled: real.settled, ...asRecord(real.result) };
-            return { kind: 'command_result', id: action, ok: true, result };
-        }
-    }
-    const bridgeArgs = { ...actArgs, args: rewritten };
-    // What the acted element shows (test id, source) is noted in `Session.command`, Harness acts too.
-    return session.command(ReticleCommand.ACT, bridgeArgs, timeoutMs);
-}
 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. 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. On a leased tab a press uses the real keyboard: Tab moves focus, and a press with a ref focuses that element first, so Enter or Space presses it as a person would. 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|insertText. 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. For insertText, defaultPrevented=true with valueChanged=true is the success path on an editor that owns its input: it cancelled beforeinput and applied the text, so it is NOT a refusal. insertText refuses with an error when the surface is not contenteditable — an EditContext editor (Monaco, CodeMirror 6) is refused too, because a scripted update fires no textupdate for its model — or when the native command exists and fails. On a leased tab a press uses the real keyboard: Tab moves focus, and a press with a ref focuses that element first, so Enter or Space presses it as a person would. Full model (real-input, throttled tabs, `reticle drive`): node_modules/@reticlehq/server/docs/usage.md §18.',
         inputSchema: {
             ref: z
                 .string()
@@ -123,7 +90,7 @@ export const ACT_TOOLS = [
             args: z
                 .record(z.string(), z.unknown())
                 .optional()
-                .describe('Action-specific arguments: { value } for fill/select (select also drives an ARIA combobox: it opens it and clicks the option by its label), { 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) or a click/dblclick (Shift+click range select), { button: "right" | "middle" } for a click (right sends contextmenu), { 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 or the key 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. For press: { keys: ["Control","k"] } holds several keys down TOGETHER (pressed in order, released in reverse) and { code } names the physical key — both stay on the in-page dispatcher, the only path that can express them. For upload: { path } is a path on disk (absolute or relative to the project root; the daemon reads the file and delivers real bytes to the file picker — this is the way to verify document-ingestion flows); or { name, content?, type? } to supply inline bytes directly.'),
+                .describe('Action-specific arguments: { value } for fill/select (select also drives an ARIA combobox: it opens it and clicks the option by its label), { text } for type/press/insertText (the key NAME, e.g. Escape or Tab, for press/type — or the text to insert for insertText), { modifiers: ["Meta","Shift"] } for a press shortcut (Meta/Control/Shift/Alt — a Cmd+K) or a click/dblclick (Shift+click range select), { button: "right" | "middle" } for a click (right sends contextmenu), { toRef } for drag (the ref to drop ON — without it the drag lands nowhere), { at: { x, y } } for click/dblclick/hover/tap/drag to act at a point of the element as fractions 0..1 of its box (a canvas has no child elements), { to: { x, y } } for drag to end at a point of the drop target (or of the source), { native: true } to force a trusted native click, { holdMs: N } to keep the pointer or the key 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. For press: { keys: ["Control","k"] } holds several keys down TOGETHER (pressed in order, released in reverse) and { code } names the physical key — both stay on the in-page dispatcher, the only path that can express them. For upload: { path } is a path on disk (absolute or relative to the project root; the daemon reads the file and delivers real bytes to the file picker — this is the way to verify document-ingestion flows); or { name, content?, type? } to supply inline bytes directly.'),
             refuseWhenThrottled: z
                 .boolean()
                 .optional()
@@ -160,8 +127,9 @@ export const ACT_TOOLS = [
             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)
+            if (paused !== undefined) {
                 return paused;
+            }
             refuseIfThrottled(session, args['refuseWhenThrottled']);
             // Where this step RUNS, read before the action — not after.
             //
@@ -169,12 +137,13 @@ export const ACT_TOOLS = [
             // ambient tape cuts journeys on this value, and stamping the destination put the sign-in click
             // at the head of the page it navigated TO: 4 of 11 auto-captured flows began with
             // `login-submit` on `/deployments`, which is the exact flow the segmentation exists to prevent.
-            const routeBefore = pathOf(session.url);
+            const routeBefore = pageOf(session.url);
             // 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)
+            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.
@@ -204,23 +173,23 @@ export const ACT_TOOLS = [
                         settled: real.settled,
                         settleReason: null,
                         result: leanActResult(real.result),
+                        ...hiddenTargetField(targetRef),
                         ...healthEnvelope(session),
                     });
                 }
                 // actCommand is the single interception point: it rewrites upload+path args to real bytes
                 // before any ACT command crosses the bridge, covering this call site and all others.
-                const result = await actCommand(deps, session, {
-                    ref: targetRef.ref,
-                    action: args['action'],
-                    args: args['args'] ?? {},
-                });
-                if (!result.ok)
+                const plain = { ref: targetRef.ref, action: args['action'], args: args['args'] ?? {} };
+                const result = await actCommand(deps, session, ReticleCommand.ACT, plain, undefined, true);
+                if (!result.ok) {
                     throw new Error(result.error ?? 'act failed');
+                }
                 captureAct(deps.recordings, args, result.result, routeBefore, session.id);
                 // lift dispatch/settle status to the envelope (a settle timeout is NOT a failure).
                 const r = asRecord(result.result);
-                if ('boolean' === typeof r['settled'])
+                if ('boolean' === typeof r['settled']) {
                     settledOutcome = r['settled'];
+                }
                 // Keep what only this call measured, so the observe that judges this window can ask whether
                 // anything happened INSIDE the target — the one fact that separates a dead control from a
                 // page that was merely busy with something else.
@@ -234,12 +203,13 @@ export const ACT_TOOLS = [
                     settled: r['settled'] ?? null,
                     settleReason: r['settleReason'] ?? null,
                     result: leanActResult(result.result),
+                    ...hiddenTargetField(targetRef),
                     ...(true === real.fellBack ? { warning: ActionWarning.REAL_INPUT_FELL_BACK } : {}),
                     ...healthEnvelope(session),
                 });
             }
             finally {
-                deps.recordings.markEnded(pathOf(session.url), session.id);
+                deps.recordings.markEnded(pageOf(session.url), session.id);
                 // Close the window on every exit (settle or throw), recording the action + settle outcome.
                 session.finishAction(undefined, settledOutcome, true === settledOutcome ? session.elapsed() - since : undefined);
             }
@@ -271,7 +241,7 @@ export const ACT_TOOLS = [
             args: z
                 .record(z.string(), z.unknown())
                 .optional()
-                .describe('Action-specific arguments: { value } for fill/select (select also drives an ARIA combobox: it opens it and clicks the option by its label), { text } for type/press (the key NAME, e.g. Escape or Tab), { modifiers: ["Meta","Shift"] } for a press shortcut or a click (Meta/Control/Shift/Alt), { button: "right" | "middle" } for a click, { toRef } for drag (the ref to drop ON — without it the drag lands nowhere), { confirmDangerous: true } for a potentially destructive control. For upload: { path } is a path on disk (absolute or relative to project root; daemon reads real bytes) or { name, content?, type? } for inline bytes.'),
+                .describe('Action-specific arguments: { value } for fill/select (select also drives an ARIA combobox: it opens it and clicks the option by its label), { text } for type/press/insertText (the key NAME, e.g. Escape or Tab, for press/type — or the text to insert for insertText), { modifiers: ["Meta","Shift"] } for a press shortcut or a click (Meta/Control/Shift/Alt), { button: "right" | "middle" } for a click, { toRef } for drag (the ref to drop ON — without it the drag lands nowhere), { at: { x, y } } for click/dblclick/hover/tap/drag to act at a point of the element as fractions 0..1 of its box (a canvas has no child elements), { to: { x, y } } for drag to end at a point of the drop target (or of the source), { confirmDangerous: true } for a potentially destructive control. For upload: { path } is a path on disk (absolute or relative to project root; daemon reads real bytes) or { name, content?, type? } for inline bytes.'),
             predicate: PredicateSchema.optional().describe('Alias for `until`.'),
             until: PredicateSchema.optional().describe('Predicate to wait for after the action completes (same shape as reticle_assert). OMIT to wait for the page to SETTLE — network + DOM idle — the deterministic default instead of a sleep. To assert a consequence AND settle, allOf them: { kind: "allOf", predicates: [<your predicate>, { kind: "settled" }] }.'),
             timeout_ms: timeoutMsSchema
@@ -287,6 +257,10 @@ export const ACT_TOOLS = [
         },
         outputSchema: {
             durable: durableOutput,
+            budgetExtendedMs: z
+                .number()
+                .optional()
+                .describe("The re-ask on the successor ran on the caller's grace: a budget extension ON PURPOSE, taken only when the departure evidence showed the page navigating. Absent for every verdict that needed no follow."),
             effect: z
                 .unknown()
                 .optional()
@@ -401,8 +375,9 @@ export const ACT_TOOLS = [
             // BEFORE the action. A body clause this session cannot answer would fail whatever the app
             // did, and on a drive that mutates state the action is not always repeatable. See #801(C).
             const bodyRefusal = bodyClauseRefusal(until, session);
-            if (bodyRefusal !== undefined)
+            if (bodyRefusal !== undefined) {
                 throw new Error(bodyRefusal);
+            }
             const timeout = asNumber(args['timeout_ms']) ?? DEFAULT_ASSERT_TIMEOUT_MS;
             // An intent declared here lands in the ledger BEFORE the verdict is drawn, which is what makes
             // the undeclared-change gap silent on THIS verdict rather than the next one: it reads the
@@ -415,8 +390,9 @@ export const ACT_TOOLS = [
             // 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)
+            if ('error' === resolved.kind) {
                 throw new Error(resolved.message);
+            }
             let since = session.elapsed();
             const actedSince = since;
             // The cursor + effect are marked after the act dispatches (below) — a refused act leaves none.
@@ -431,7 +407,7 @@ export const ACT_TOOLS = [
             // Was the consequence ALREADY TRUE, and what did that reading say? See act/already-true.ts.
             const { alreadyTrue, alreadyTrueHiddenMatch, alreadyTrueEvidence, baselines } = await readAlreadyTrue(session, until, since);
             // Same as the ACT handler: the route this step RAN on, before the action can move the app.
-            const routeBeforeWait = pathOf(session.url);
+            const routeBeforeWait = pageOf(session.url);
             // Recorded in `finally`, once the verdict is known — see captureVerdictedAct. `held`: the
             // action made the declared claim hold.
             let dispatched;
@@ -445,14 +421,15 @@ export const ACT_TOOLS = [
                 // returns null instead (see act-preflight.ts for why a write is never re-sent), and the
                 // successor block below then asks whether the consequence held on the NEW document — a
                 // green if it did, an honest observation_lost if it did not.
-                const actResult = await dispatchAct(() => actCommand(deps, session, {
+                const actResult = await dispatchAct(() => actCommand(deps, session, ReticleCommand.ACT, {
                     ref: resolved.ref,
                     action: args['action'],
                     args: confirmedByDeclaration(asRecord(args['args']), args['target'], untilNamed),
                 }));
                 if (actResult !== null) {
-                    if (!actResult.ok)
+                    if (!actResult.ok) {
                         throw new Error(actResult.error ?? 'act failed');
+                    }
                     dispatched = { result: actResult.result };
                     // Dispatched — now this act owns the cursor and the effect. Marking its OWN measurement
                     // also stops the spread below from inheriting an earlier reticle_act's action and
@@ -463,9 +440,7 @@ export const ACT_TOOLS = [
                 const predicateStarted = session.elapsed();
                 let verdict = null === actResult
                     ? { pass: false, observationLost: true }
-                    : timeout > 0
-                        ? await waitForPredicate(session, until, timeout, since, baselines)
-                        : await evaluatePredicate(session, until, since, true, baselines);
+                    : await evaluateAfterAct(session, until, timeout, since, baselines);
                 // The SDK may have gone away mid-act — see act-observation.ts.
                 const followed = await followLostObservation({
                     sessions: deps.sessions,
@@ -473,23 +448,28 @@ export const ACT_TOOLS = [
                     verdict,
                     timeout,
                     predicateStarted,
+                    since,
+                    failedFollowGraceMs: NAVIGATION_FOLLOW_GRACE_MS,
                     reevaluate: (next, budget) => waitForPredicate(next, until, budget, 0, baselines),
                 });
-                if (followed.followed)
+                if (followed.followed) {
                     since = 0;
+                }
                 session = followed.session;
                 verdict = followed.verdict;
                 // After a match, let the app finish before the window closes — see act/after-match.ts.
                 if (verdict.pass && timeout > 0) {
                     const left = () => timeout - (session.elapsed() - predicateStarted);
                     const reverted = await finishAfterMatch(session, until, since, baselines, left);
-                    if (reverted !== undefined)
+                    if (reverted !== undefined) {
                         verdict = { pass: false, failureReason: reverted, observed: reverted };
+                    }
                     verdict = await awaitShownMatch(session, until, since, baselines, verdict, left);
                 }
                 const r = asRecord(actResult?.result);
-                if ('boolean' === typeof r['settled'])
+                if ('boolean' === typeof r['settled']) {
                     settledOutcome = r['settled'];
+                }
                 // Where the acted element is written, captured at act time even if the action unmounted it.
                 const actedSource = sourceOf(r['source']);
                 // Remembered so a LATER assertion can name a file with no element to point at, and so the
@@ -507,6 +487,9 @@ export const ACT_TOOLS = [
                 // Read before the capsule, which needs it: a window the buffer trimmed cannot state an
                 // absolute about what did NOT happen. See CausalSummary.truncated.
                 const bufferLost = session.lostSince(since);
+                const impeachForLoss = bufferLost &&
+                    (restsOnCompleteWindow(until) ||
+                        (false === verdict.pass && failingClauseReadsLostChannel(until, windowEvents)));
                 const capsule = verdict.pass
                     ? undefined
                     : buildDivergenceCapsule(links, windowEvents, bufferLost);
@@ -528,11 +511,13 @@ export const ACT_TOOLS = [
                 // stronger than this block. Grade from the strongest asserted consequence; integrity from evictions.
                 // Coverage: cross-origin frames / other blind spots the SDK reported during this window mean the
                 // verdict didn't see everything — say so, never imply full coverage.
-                const spots = blindSpotsFromState(session.blindSpots(), session.runtime);
+                const prior = since > 0 ? (await session.queryEvents({ since: 0 })).filter((e) => e.t < since) : [];
+                const canvas = canvasPaintSpots(windowEvents, { actionSince: since, prior });
+                const spots = [...blindSpotsFromState(session.blindSpots(), session.runtime), ...canvas];
                 // The window's own counts, so sampling before it is not described as this window's (#1414).
                 const windowSpots = blindSpotsFromState(session.blindSpots(since), session.runtime);
                 const coverage = buildCoverageStatement(spots, windowSpots);
-                const absenceBlindSpot = absenceBlindSpotNote(until, spots);
+                const absenceBlindSpot = absenceBlindSpotNote(until, spots, windowEvents);
                 // A green resting on hidden matches says the node exists, not that it shows (#1408).
                 const hiddenMatch = hiddenMatchNote(until, verdict.evidence);
                 // Nothing subscribed ⇒ the state channel is dark, and the summary must say so rather than
@@ -567,13 +552,7 @@ export const ACT_TOOLS = [
                 const honesty = buildHonestyBlock({
                     grade,
                     attribution: 'window',
-                    // Did the buffer lose scarce evidence FROM THIS WINDOW — not "did it evict anything while
-                    // the action ran", which was the previous rule and which is true on essentially every live
-                    // page. Age eviction retires everything past 60s on every push, and the churn floor is
-                    // sacrificed on purpose; neither costs this verdict a single event it needed. In the
-                    // field this made `unclean_capture` the dominant cause of `unknown`, reported for
-                    // evictions that happened outside the window they impeached.
-                    truncated: bufferLost,
+                    truncated: impeachForLoss,
                     coveragePartial: Coverage.PARTIAL === coverage.coverage,
                     ...(coverage.note === undefined ? {} : { coverageNote: coverage.note }),
                     // Settlement no longer vetoes a declared consequence that held, so the fact is carried
@@ -609,8 +588,8 @@ export const ACT_TOOLS = [
                 // flagship path, and nothing said so: the finding was simply never produced.
                 //
                 // 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) : [];
+                // `windowEvents`, exactly as on the assert path. It is read above, before coverage, because the
+                // canvas-paint spot (#1525) learns the last canvas digest from it too.
                 //
                 // `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.
@@ -625,9 +604,10 @@ export const ACT_TOOLS = [
                     namedNetUrls: declared.netUrls,
                     repeatableNetUrls: declared.repeatableNetUrls,
                     // 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,
+                    // not evidence the destination rendered or the route moved — `alreadyTrue` decides that, once.
+                    ...provedConsequences(declared, verdict.pass && !alreadyTrue),
                     ...session.lastAct.effect(),
+                    ...namedReactions(declared),
                     currentDocumentId: session.currentDocumentId,
                     currentEditEpoch: session.currentEditEpoch,
                     appOrigin: session.url,
@@ -645,8 +625,8 @@ export const ACT_TOOLS = [
                 });
                 const outcomeUnread = unreadWriteLabels(windowEvents);
                 const stillInFlight = inFlightRequestLabels(windowEvents, session.url, session.background);
-                // A click on a disabled control cannot cause anything, nor one no person could make.
-                const inconclusive = verdict.inconclusive ?? actTargetNote(verdict.pass, actResult?.result);
+                // A timed-out read says why; a disabled or unreachable target cannot cause anything.
+                const inconclusive = actInconclusive(verdict, actResult?.result, session);
                 const { decision, durable } = await withDurability(args['durable'], until, decideVerified({
                     pass: verdict.pass,
                     // Threaded rather than looked up: decideVerified is pure and has no session.
@@ -686,10 +666,11 @@ export const ACT_TOOLS = [
                     unsettled: {
                         waitedFor: describeWaitTarget(until),
                         stillInFlight,
-                        // The retry loop that leaves nothing outstanding — see repeatedRequestLabels.
                         repeated: repeatedRequestLabels(windowEvents),
                     },
                     ...(namedNetIsInFlight(until, stillInFlight) ? { namedRequestInFlight: true } : {}),
+                    ...(impeachForLoss && false === verdict.pass ? { bufferLostEvidence: true } : {}),
+                    ...withDeclinedDialog(windowEvents),
                 }), (part) => reloadAndRecheck(deps, session, part, timeout));
                 noteProved(session, String(decision.verified), actResult?.result);
                 // Computed once: the verdict block reports it, and the instrumentation gaps are a second
@@ -785,6 +766,7 @@ export const ACT_TOOLS = [
                     // An unobserved act has no effect to report, and inventing an empty one would read as
                     // "the page did nothing" — a claim about the app, from a call that never saw it.
                     ...(null === actResult ? {} : { effect: leanActResult(actResult.result) }),
+                    ...hiddenTargetField(resolved),
                     verdict,
                     // Promoted out of `effect` on red only. On green nobody needs it and it is noise; on red it
                     // is the first thing the agent wants, and burying a file:line inside the effect block is
@@ -827,15 +809,21 @@ export const ACT_TOOLS = [
                     // Without its summary: it is byte-identical to `summary` two fields up. See wireCapsule.
                     ...(capsule === undefined ? {} : { capsule: wireCapsule(capsule) }),
                     ...(0 === greenRadius.length ? {} : { blastRadius: greenRadius }),
+                    // The re-ask on the successor ran on the caller's grace — a budget extension on purpose,
+                    // declared so the agent can see the extra time it was given (#2009).
+                    ...(followed.budgetExtendedMs === undefined
+                        ? {}
+                        : { budgetExtendedMs: followed.budgetExtendedMs }),
                     since,
                     ...(session.id === actedSessionId ? {} : { sessionId: session.id }),
                     ...healthEnvelope(currentOf(deps.sessions, session)),
                 });
             }
             finally {
-                if (dispatched !== undefined)
+                if (dispatched !== undefined) {
                     captureVerdictedAct(deps.recordings, args, dispatched.result, routeBeforeWait, held, session.id, wroteSince(acted, actedSince));
-                deps.recordings.markEnded(pathOf(currentOf(deps.sessions, session).url), session.id);
+                }
+                deps.recordings.markEnded(pageOf(currentOf(deps.sessions, session).url), session.id);
                 acted.finishAction(verdictEffect, settledOutcome, true === settledOutcome ? acted.elapsed() - actedSince : undefined);
             }
         },

package/dist/surface/tools/agent/build-staleness.d.ts

@@ -1,4 +1,4 @@
-export declare const STALE_BUILD_NOTICE = "Reticle's code on disk changed after this daemon started, so it is still running the old build. Restart it (`npx @reticlehq/server restart`) and retry before trusting a fix to Reticle itself.";
+export declare const STALE_BUILD_NOTICE = "Reticle's code on disk changed after this daemon started, so it is still running the old build. Restart it (`npx @reticlehq/server serve --restart`) and retry before trusting a fix to Reticle itself.";
 /** Newest `.js` mtime under `dir`, or 0 when it cannot be read. */
 export declare function newestJsMtime(dir: string): number;
 /** A watcher over one directory, started now. Exported for tests; the daemon uses the default. */

package/dist/surface/tools/agent/build-staleness.js

@@ -14,7 +14,7 @@ import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 /** How often the walk may run. A few hundred stats, so cheap, but not on every call. */
 const CHECK_EVERY_MS = 30_000;
-export const STALE_BUILD_NOTICE = "Reticle's code on disk changed after this daemon started, so it is still running the old build. Restart it (`npx @reticlehq/server restart`) and retry before trusting a fix to Reticle itself.";
+export const STALE_BUILD_NOTICE = "Reticle's code on disk changed after this daemon started, so it is still running the old build. Restart it (`npx @reticlehq/server serve --restart`) and retry before trusting a fix to Reticle itself.";
 /** `dist/` of this package: this file sits at dist/surface/tools/agent/. */
 const DIST_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
 /** Newest `.js` mtime under `dir`, or 0 when it cannot be read. */

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

@@ -8,40 +8,19 @@ import { hiddenMatchNote } from '@reticlehq/engine/evidence/already-true.js';
 import { provenExpectedLinks, } from '@reticlehq/engine/question/predicate/predicate.js';
 import { findContradictions, } from '@reticlehq/engine/disagreement/contradictions.js';
 import { crashedRuleNotes } from '@reticlehq/engine/disagreement/contradiction-folds.js';
-import { declaredExpectations, declaresBodyIndependentChannel, } from '@reticlehq/engine/question/declared.js';
-import { absenceBlindSpotNote, blindSpotsFromState, buildCoverageStatement, restsOnCompleteWindow, Coverage, impeachesCapture, transportGapNote, } from '@reticlehq/engine/evidence/blind-spots.js';
+import { declaredExpectations, declaresBodyIndependentChannel, provedConsequences, } from '@reticlehq/engine/question/declared.js';
+import { absenceBlindSpotNote, blindSpotsFromState, buildCoverageStatement, failingClauseReadsLostChannel, restsOnCompleteWindow, Coverage, impeachesCapture, transportGapNote, } from '@reticlehq/engine/evidence/blind-spots.js';
 import { buildHonestyBlock } from '@reticlehq/engine/evidence/honesty.js';
 import { acceptedWriteLabels, hasAcceptedWrite, } from '@reticlehq/engine/evidence/accepted-write.js';
 import { unreadWriteLabels, unreadWriteReason } from '@reticlehq/engine/evidence/unread-outcome.js';
-import { decideVerified } from '@reticlehq/engine/evidence/verified.js';
+import { decideVerified, withDeclinedDialog } from '@reticlehq/engine/evidence/verified.js';
 import { describeWaitTarget, namedNetIsInFlight } from '@reticlehq/engine/evidence/unsettled.js';
 import { inFlightRequestLabels, repeatedRequestLabels, } from '../act/settle-in-flight.js';
 import { gradeOfPredicate } from './assert-grade.js';
 import { assertSource, stampedSourceIn } from './assert-source.js';
 import { VerdictAttribution, verdictAttributionOf } from '@reticlehq/core';
 import { noteSourceSeen } from '../../../portal/session/recorded-gaps.js';
-import { sdkBehindNote } from '../../../portal/session/session-info.js';
-// Unanchored: the engine prefixes the reason with "the page did not answer:".
-const COMMAND_TIMEOUT = /command '[^']*' timed out after (\d+)ms/;
-/**
- * The cause and the one fix for a read that came back `unknown`, in place of a bare fact (#1990).
- * A page whose SDK is behind this daemon may not serve `match` at all, so the fix is the same
- * SDK-behind sentence the listing shows. On a current page the read ran out of the assertion's own
- * budget, and the fix is more of it.
- */
-function diagnoseTimeout(reason, session) {
-    const behind = sdkBehindNote(session);
-    if (behind !== undefined) {
-        return `${reason} ${behind}`;
-    }
-    const granted = COMMAND_TIMEOUT.exec(reason)?.[1];
-    if (granted === undefined) {
-        return reason;
-    }
-    return (`${reason} This read was bounded by what the assertion's budget had left ` +
-        `(${granted}ms): the budget ran out while the page was still working. ` +
-        'Give the assertion more time with `timeout_ms`.');
-}
+import { diagnoseTimeout } from '../act/act-observation.js';
 /**
  * The honesty verdict for a plain `reticle_assert`.
  *
@@ -84,7 +63,6 @@ changeUndeclared) {
     // The window's own counts, so sampling before it is not described as this window's (#1414).
     const windowSpots = blindSpotsFromState(session.blindSpots(since), session.runtime);
     const statement = buildCoverageStatement(spots, windowSpots);
-    const absenceBlindSpot = absenceBlindSpotNote(predicate, spots);
     // A green resting on hidden matches says the node exists, not that it shows (#1408).
     const hiddenMatch = hiddenMatchNote(predicate, evidence);
     // Omitted entirely when coverage is full, so an intact page pays nothing and the field's PRESENCE
@@ -96,6 +74,8 @@ changeUndeclared) {
         }
         : {};
     const windowEvents = await session.queryEvents({ since });
+    // The window lets a target the page was seen to remove escape the virtualized blind spot.
+    const absenceBlindSpot = absenceBlindSpotNote(predicate, spots, windowEvents);
     // Everything before the window, passed as LEARNING material only. A scale error disagrees with a
     // value the API stated earlier in the session, which an action-scoped window can never contain —
     // measured live, `observe` over a wide window reported `unit-mismatch` while `assert` on the same
@@ -120,7 +100,7 @@ changeUndeclared) {
         expectedFailures: declared.netFailures,
         namedNetUrls: declared.netUrls,
         repeatableNetUrls: declared.repeatableNetUrls,
-        renderProved: pass && declared.rendersContent,
+        ...provedConsequences(declared, pass),
         ...(actCursor !== undefined && actCursor >= since ? { actionSince: actCursor } : {}),
     });
     // Only a spot that IMPEACHES the capture downgrades a general verdict. Structural boundaries are
@@ -162,10 +142,7 @@ changeUndeclared) {
     const stillInFlight = inFlightRequestLabels(windowEvents, session.url, session.background);
     const rawInconclusive = inconclusive ?? (!pass ? session.preconditionFailure?.() : undefined);
     // A timed-out page read is the one `unknown` whose cause and fix are knowable here (#1990).
-    let effectiveInconclusive = rawInconclusive;
-    if (rawInconclusive !== undefined && COMMAND_TIMEOUT.test(rawInconclusive)) {
-        effectiveInconclusive = diagnoseTimeout(rawInconclusive, session);
-    }
+    const effectiveInconclusive = diagnoseTimeout(rawInconclusive, session);
     /**
      * Does a green here rest on the window having been COMPLETE?
      *
@@ -180,13 +157,13 @@ changeUndeclared) {
     /**
      * The buffer evicted scarce evidence from this window.
      *
-     * assert never consulted the buffer at all, on the reasoning that it "observes an already-open
-     * window" — but eviction happens on push regardless of who opened the window, so
-     * `{ console, absent: true }` returned `yes` over a window whose evidence was gone, which is
-     * absence of evidence read as evidence of absence. The act path needs no `restsOnComplete` guard:
-     * its cursor is the action's own.
+     * Two cases. (1) An ABSENCE claim needs a complete window; things dropped are the disproof it
+     * cannot see. (2) A FAILING positive `allOf` whose NET/SIGNAL/LOG child has no evidence left in
+     * the window — the child might have failed because the buffer dropped the request, not because
+     * the app never made it (#1231). Only the second reads the events; the first is structural.
      */
-    const bufferLost = session.lostSince(since) && restsOnComplete;
+    const bufferLost = session.lostSince(since) &&
+        (restsOnComplete || (false === pass && failingClauseReadsLostChannel(predicate, windowEvents)));
     /** The durable ledger refused writes, on a query path that read from it. Same rule, other store. */
     const ledgerLost = ledgerClosed && restsOnComplete;
     const decision = decideVerified({
@@ -209,6 +186,8 @@ changeUndeclared) {
         ...(absenceBlindSpot === undefined ? {} : { absenceBlindSpot }),
         ...(hiddenMatch === undefined ? {} : { hiddenMatch }),
         ...(namedNetIsInFlight(predicate, stillInFlight) ? { namedRequestInFlight: true } : {}),
+        ...(bufferLost && false === pass ? { bufferLostEvidence: true } : {}),
+        ...withDeclinedDialog(windowEvents),
         honesty: buildHonestyBlock({
             grade: gradeOfPredicate(predicate),
             attribution: 'window',

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

@@ -2,7 +2,7 @@ import { carryReticleIdentity, LEASE_ACQUIRE_TOOL } from './lease-tools.js';
 import { z } from 'zod';
 import { navigateResult } from './act/navigation/navigate-result.js';
 import { absoluteTarget, awaitArrival, idsOpenAtDispatch, ARRIVAL_TIMEOUT_MS, } from './act/navigation/navigate-arrival.js';
-import { reloadResult } from './act/navigation/reload-result.js';
+import { HardReload, hardReloadOf, reloadResult } from './act/navigation/reload-result.js';
 import { waitForReconnect, RELOAD_RECONNECT_TIMEOUT_MS, } from '../../portal/session/session-reconnect.js';
 import { NO_SESSION_CONNECTED_ERROR, ReticleCommand, SESSION_STARTED_NOTE, SessionStartedVia, relativeUrlNoSession, } from '@reticlehq/core';
 import { ReticleTool } from '@reticlehq/core';
@@ -106,7 +106,7 @@ export const BROWSER_TOOLS = [
             hard: z
                 .boolean()
                 .optional()
-                .describe('With reload:true, bypass the browser cache (Cmd+Shift+R). Default: false.'),
+                .describe('With reload:true, bypass the browser cache (Cmd+Shift+R) on a leased tab. On a tab Reticle does not drive, only the document is fetched again; scripts and modules can still come from the cache. Default: false.'),
             timeout_ms: timeoutMsSchema
                 .optional()
                 .describe('How long to wait for the page to come back (the SDK reconnecting at the new URL, or under the same id on a reload) before answering confirmed:false. Default 5000. 0 looks once without waiting. An SPA reattaching under HMR has been measured at 30-60s — say so here instead of polling reticle_sessions.'),
@@ -133,6 +133,8 @@ export const BROWSER_TOOLS = [
             /** Present only when no session was connected and this call opened one on the URL. */
             sessionStarted: SessionStartedSchema.optional(),
             note: z.string().optional(),
+            /** On a `hard` reload: whether the browser ignored its cache, or only the document was fetched again. */
+            hardReload: z.nativeEnum(HardReload).optional(),
         },
         handler: async (deps, args) => {
             // reload:true is the absorbed reticle_refresh — same command, one fewer advertised tool.
@@ -148,9 +150,13 @@ export const BROWSER_TOOLS = [
                 // coming back `contradicted` by hundreds of 500s against resources that were already gone.
                 before.lastAct.markNavigated(before.elapsed());
                 deps.recordings.markNavigated();
-                await commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.REFRESH, {
-                    hard: true === args['hard'],
-                });
+                const hard = true === args['hard'];
+                // A leased tab reloads through the browser with the cache ignored. The page itself can only
+                // re-fetch its document: scripts and modules still come from the cache (#1785).
+                const throughBrowser = hard && true === (await deps.pool?.hardReloadLease(before.id));
+                if (!throughBrowser) {
+                    await commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.REFRESH, { hard });
+                }
                 // WAIT for the page to come back, rather than telling the agent to. The id survives the
                 // reload, but the seconds between dispatch and the new HELLO are seconds in which every call
                 // lands in the old, disconnected session — measured as reticle_run failing 5 of 5 on a page
@@ -165,7 +171,7 @@ export const BROWSER_TOOLS = [
                 // Not a bare `{ ok: true }`. The URL branch below already discloses that `ok` means
                 // DISPATCHED — the reload branch had identical semantics and said nothing, on the path most
                 // likely to need it. See reload-result.
-                return reloadResult(back, timeoutMs);
+                return reloadResult(back, timeoutMs, hardReloadOf(hard, throughBrowser));
             }
             const requested = asString(args['url']);
             if (requested === undefined || 0 === requested.length) {