@reticlehq/server 2.10.0 → 2.12.0

package/dist/tools/act-tools.js

@@ -8,7 +8,7 @@ import { resolveTargetRef } from './resolve-target.js';
 import { z } from 'zod';
 import { aliasParam } from './alias-args.js';
 import { captureAct, compileSequenceStep } from '../flows/replay.js';
-import { ActionType, ActionWarning, CaptureLoss, DEFAULT_ASSERT_TIMEOUT_MS, InputMode, ReticleCommand, Verified, PredicateKind, } from '@reticlehq/core';
+import { ActionType, ActionWarning, CaptureLoss, DEFAULT_ASSERT_TIMEOUT_MS, InputMode, ReticleCommand, Verified, VerifiedReason, PredicateKind, } from '@reticlehq/core';
 import { assertNativeInputSupported } from './act-danger.js';
 import { leanActResult, mutatedWithin } from './act-view.js';
 import { ReticleTool } from './tool-names.js';
@@ -16,26 +16,52 @@ 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 { gapsForAction } from '../honesty/instrumentation-gaps.js';
+import { noteSessionGaps } from '../honesty/gap-ledger.js';
+import { isChangeUndeclared } from '../honesty/undeclared-change.js';
+import { openSessionIntents } from '../intent/open-intents.js';
+import { dischargeInlineIntent, inlineVerdictId, linkInlineIntent, } from '../intent/inline-intent.js';
+import { declaresState } from '../events/predicate-asks.js';
+import { isStateUnwatched } from '../honesty/blind-spots.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 { declaredExpectations, declaresBodyIndependentChannel } 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 { BlindSpotKind, buildCoverageStatement, blindSpotsFromState, transportGapNote, Coverage, impeachesCapture, } from '../honesty/blind-spots.js';
+import { buildCoverageStatement, blindSpotsFromState, transportGapNote, Coverage, impeachesCapture, } from '../honesty/blind-spots.js';
 import { hasAcceptedWrite } from '../honesty/accepted-write.js';
 import { unreadWriteLabels } from '../honesty/unread-outcome.js';
 import { evaluatePredicate, waitForPredicate, provenExpectedLinks, PredicateSchema, } from '../events/predicate.js';
+import { awaitDocumentSuccessor } from '../session/session-successor.js';
 import { healthEnvelope, refuseIfThrottled } from '../session/session-health.js';
 import { pausedShortCircuit, pausedOutputShape, withControl, PAUSED_NO_VERDICT, } from '../session/control-envelope.js';
 import { asString, asNumber, asRecord, sourceOf } from './tools-helpers.js';
-import { sessionIdShape } from './tool-kit.js';
+import { intentArg, sessionIdShape } from './tool-kit.js';
 import { asActionType, gradeOf } from './act-helpers.js';
-import { tryRealInput } from './real-input-attempt.js';
+import { tryRealInput, rewriteUploadArgs } from './real-input-attempt.js';
+/**
+ * Single dispatch point for every ACT and ACT_SEQUENCE command.
+ *
+ * This is the seam the reviewer asked for: instead of wiring rewriteUploadArgs at three separate
+ * call sites (reticle_act, reticle_act_and_wait, reticle_act_sequence) we intercept once here,
+ * which also covers flow-replay, crawl, and any future dispatch site that goes through this helper.
+ *
+ * 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.
+ */
+async function actCommand(deps, session, actArgs, timeoutMs) {
+    const rewritten = await rewriteUploadArgs(deps, 'string' === typeof actArgs['action'] ? actArgs['action'] : '', asRecord(actArgs['args']));
+    const bridgeArgs = { ...actArgs, args: rewritten };
+    return timeoutMs !== undefined
+        ? session.command(ReticleCommand.ACT, bridgeArgs, timeoutMs)
+        : session.command(ReticleCommand.ACT, bridgeArgs);
+}
 /**
  * Narrow the wire's `action` to a real ActionType, or undefined.
  *
@@ -109,7 +135,7 @@ export const ACT_TOOLS = [
             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), { 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.'),
+                .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. 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()
@@ -175,7 +201,7 @@ export const ACT_TOOLS = [
                     settledOutcome = real.settled ?? undefined;
                     // Native input reports no synthetic effect block, so nothing measured in-target: undefined
                     // (the weaker empty-window test), never a fabricated zero.
-                    session.lastAct.markActed(since, action, undefined);
+                    session.lastAct.markActed(since, action, undefined, asString(args['ref']));
                     return withControl(session, {
                         since,
                         inputMode: InputMode.REAL,
@@ -186,7 +212,9 @@ export const ACT_TOOLS = [
                         ...healthEnvelope(session),
                     });
                 }
-                const result = await session.command(ReticleCommand.ACT, {
+                // 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'] ?? {},
@@ -201,7 +229,7 @@ export const ACT_TOOLS = [
                 // Keep what only this call measured, so the observe that judges this window can ask whether
                 // anything happened INSIDE the target — the one fact that separates a dead control from a
                 // page that was merely busy with something else.
-                session.lastAct.markActed(since, action, mutatedWithin(r));
+                session.lastAct.markActed(since, action, mutatedWithin(r), asString(args['ref']));
                 return withControl(session, {
                     since,
                     inputMode: InputMode.SYNTHETIC,
@@ -276,7 +304,7 @@ export const ACT_TOOLS = [
                 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);
+                        const result = await actCommand(deps, session, { ref: step['ref'], action: step['action'], args: step['args'] ?? {} }, perStepTimeout);
                         if (!result.ok) {
                             stalledAt = i;
                             stepResults.push({
@@ -368,7 +396,7 @@ export const ACT_TOOLS = [
             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), { 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.'),
+                .describe('Action-specific arguments: { value } for fill/select, { text } for type/press (the key NAME, e.g. Escape or Tab), { modifiers: ["Meta","Shift"] } for a press shortcut (Meta/Control/Shift/Alt), { toRef } for drag (the ref to drop ON — without it the drag lands nowhere), { confirmDangerous: true } for a potentially destructive control. For upload: { path } is a path on disk (absolute or relative to project root; daemon reads real bytes) or { name, content?, type? } for inline bytes.'),
             predicate: PredicateSchema.optional().describe('Alias for `until` (the name reticle_assert / reticle_wait_for use).'),
             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
@@ -379,6 +407,7 @@ export const ACT_TOOLS = [
                 .boolean()
                 .optional()
                 .describe('Throw if the tab is throttled. Default: false.'),
+            intent: intentArg,
             ...sessionIdShape,
         },
         outputSchema: {
@@ -432,12 +461,20 @@ export const ACT_TOOLS = [
                 .array(z.unknown())
                 .optional()
                 .describe('Channels that DISAGREE about this action — the UI advanced while its write failed, a success signal fired over a failed request, a response changed nothing, a duplicate fired, a request never settled. OMITTED when clean. Treat any entry as a finding even when the verdict is green: a passing assertion and a contradicted channel is exactly the false green this exists to catch.'),
+            instrumentationGaps: z
+                .array(z.unknown())
+                .optional()
+                .describe('What the APP did not tell Reticle, and the one change that would fix it — each entry is { kind, missing, cost, fix, source?, ref? }. Reported ONLY where an absence made THIS verdict weaker (a red that cannot name a file:line, a state assertion with no registered store, a DOM change no signal announced, a route change nothing signalled); never a survey of the page, so an entry is always work worth doing now. OMITTED when the app told Reticle everything it needed. Applying `fix` makes every later verdict on this app stronger, not just this one.'),
             honesty: z
                 .unknown()
                 .describe('The verdict trust block { grade, attribution, coverage, integrity, envelope? } — a green never looks stronger than this. Gate on grade ≥ net AND integrity.clean. Fields that were not measured are OMITTED rather than reported as zero, so treat an absent `envelope` as "not sampled", never as a failure.'),
             since: z
                 .number()
                 .describe('Cursor for this act — pass to reticle_observe/reticle_assert for the full timeline.'),
+            sessionId: z
+                .string()
+                .optional()
+                .describe('The session that answered, when a full-document navigation replaced the one that was acted on. Absent when the original session survived.'),
             session: z
                 .object({ lastSeenMs: z.number(), throttled: z.boolean(), focused: z.boolean() })
                 .optional(),
@@ -445,7 +482,9 @@ export const ACT_TOOLS = [
             ...pausedOutputShape,
         },
         handler: async (deps, args) => {
-            const session = deps.sessions.resolve(asString(args['sessionId']));
+            let session = deps.sessions.resolve(asString(args['sessionId']));
+            const acted = session;
+            const actedSessionId = session.id;
             // Live-control: refuse to drive the page (no act, no predicate eval) while paused.
             //
             // A VERDICT rides out with the refusal. This is the one tool here that promises `verified`,
@@ -464,6 +503,10 @@ export const ACT_TOOLS = [
                 ? parsePredicate(withUntil['until'])
                 : { kind: PredicateKind.SETTLED };
             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
+            // ledger below and finds something open. The discharge comes after that read.
+            const intentId = await linkInlineIntent(deps, asString(args['sessionId']), asString(args['intent']), PredicateKind.SETTLED === until.kind ? undefined : until);
             // 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']));
@@ -472,12 +515,17 @@ export const ACT_TOOLS = [
             const resolved = await resolveActTarget(session, args);
             if ('error' === resolved.kind)
                 throw new Error(resolved.message);
-            const since = session.elapsed();
+            let since = session.elapsed();
+            const actedSince = since;
             // 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
             // (the whole point of act_and_wait) attribute to this action. finishAction fires after the wait.
             session.beginAction(ReticleTool.ACT_AND_WAIT, asRecord(args));
             let settledOutcome;
+            // The verdict, written into the action record so a LATER turn can read what this one proved.
+            // A verdict that lives only in the response lives only in the agent's context window, which is
+            // exactly the copy a compaction destroys — see runs/run-context.ts.
+            let verdictEffect;
             // Was the declared consequence ALREADY TRUE? Only asked for predicates that read live DOM
             // state — event-based ones are floored at this act's cursor and cannot be satisfied by the
             // past, so they need no pre-check and pay nothing. One extra query, on the path where a green
@@ -486,7 +534,8 @@ export const ACT_TOOLS = [
                 ? (await evaluatePredicate(session, until, since, false)).pass
                 : false;
             try {
-                const actResult = await session.command(ReticleCommand.ACT, {
+                // actCommand is the single interception point for upload+path rewrite.
+                const actResult = await actCommand(deps, session, {
                     ref: resolved.ref,
                     action: args['action'],
                     args: args['args'] ?? {},
@@ -496,12 +545,31 @@ export const ACT_TOOLS = [
                 captureAct(deps.recordings, args, actResult.result);
                 // Dispatched — now this act owns the cursor and the effect. Marking its OWN measurement also
                 // stops the spread below from inheriting an earlier reticle_act's action and mutation count.
-                session.lastAct.markActed(since, asString(args['action']), mutatedWithin(asRecord(actResult.result)));
+                session.lastAct.markActed(since, asString(args['action']), mutatedWithin(asRecord(actResult.result)), asString(args['ref']));
                 // 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
+                let verdict = timeout > 0
                     ? await waitForPredicate(session, until, timeout, since)
                     : await evaluatePredicate(session, until, since);
+                // A full-document navigation tears the SDK down mid-wait. `navigate` already waits for the
+                // HELLO and returns the new id; this path used to grade `observation_lost` and leave the
+                // agent holding a dead id, so the next assert failed even though the new page had loaded.
+                // Follow the unique same-origin successor (the awaitArrival idea, without a known URL) and
+                // evaluate there. Two live tabs at that origin is still a guess — we do not follow then.
+                if (true === verdict.observationLost && timeout > 0) {
+                    const remaining = timeout - (session.elapsed() - predicateStarted);
+                    const next = remaining > 0 ? await awaitDocumentSuccessor(deps.sessions, session, remaining) : null;
+                    if (next !== null) {
+                        // Compute leftover on the departed session before we point `session` at the successor —
+                        // the new session's elapsed() starts at 0 and would refund the whole budget.
+                        const leftover = timeout - (session.elapsed() - predicateStarted);
+                        session = next;
+                        since = 0;
+                        if (leftover > 0) {
+                            verdict = await waitForPredicate(session, until, leftover, 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
@@ -539,7 +607,8 @@ export const ACT_TOOLS = [
                 const actedSource = sourceOf(r['source']);
                 // Remembered on the session so a LATER assertion can name a file even when its failure has no
                 // element to point at — a signal that never fired, a request that was never made.
-                session.lastAct.markSource(actedSource === undefined ? undefined : `${actedSource.file}:${String(actedSource.line)}`);
+                const actedSourceLabel = actedSource === undefined ? undefined : `${actedSource.file}:${String(actedSource.line)}`;
+                session.lastAct.markSource(actedSourceLabel);
                 const windowEvents = session.eventsSince(since);
                 const trace = summarizeReaction(buildReactionReport(windowEvents, session.elapsed() - since));
                 // The bounded Tier-1 causal summary — net/console/state/storage diffs the trace's counts miss.
@@ -561,7 +630,7 @@ export const ACT_TOOLS = [
                 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);
+                const stateUnwatched = isStateUnwatched(spots);
                 // Only a spot that IMPEACHES the capture belongs in integrity — see impeachesCapture. A
                 // structural boundary (virtualized rows, a cross-origin frame) is reported as coverage and
                 // must not downgrade a verdict about what WAS observed.
@@ -582,8 +651,11 @@ export const ACT_TOOLS = [
                     ...(gapNote === undefined ? [] : [CaptureLoss.TRANSPORT_GAP]),
                     ...(impeaching.note === undefined ? [] : [CaptureLoss.BLIND_SPOT]),
                 ];
+                // Named because the discharge below records the same grade the verdict reports, rather than a
+                // second reading of the same evidence that could drift from it.
+                const grade = gradeOf(gradedLinks);
                 const honesty = buildHonestyBlock({
-                    grade: gradeOf(gradedLinks),
+                    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
@@ -636,6 +708,8 @@ export const ACT_TOOLS = [
                     // not evidence the destination rendered either — `alreadyTrue` decides that, once.
                     renderProved: verdict.pass && !alreadyTrue && declared.rendersContent,
                     ...session.lastAct.effect(),
+                    currentDocumentId: session.currentDocumentId,
+                    currentEditEpoch: session.currentEditEpoch,
                 });
                 // 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.
@@ -648,6 +722,9 @@ export const ACT_TOOLS = [
                     // 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,
+                    // A body-independent declaration that held is a channel the unread payload does not own.
+                    // Omit when false: a net-only `until` must still hit `outcome_unread`.
+                    ...(declaresBodyIndependentChannel(until) ? { independentOfBody: true } : {}),
                     ...(alreadyTrue ? { alreadyTrue } : {}),
                     // An assertion nobody could evaluate must not be reported as one the app failed.
                     ...(verdict.inconclusive === undefined ? {} : { inconclusive: verdict.inconclusive }),
@@ -672,6 +749,62 @@ export const ACT_TOOLS = [
                         repeated: repeatedRequestLabels(windowEvents),
                     },
                 });
+                // Computed once: the verdict block reports it, and the instrumentation gaps are a second
+                // reading of the same evidence rather than a new observation.
+                const actionSummary = causalSummary(windowEvents, { stateUnwatched });
+                // Asked of every verdict drawn after an observed edit, not once per edit — see
+                // isChangeUndeclared for why repeating it is disclosure rather than nagging.
+                // Read ONCE and used twice: `changeUndeclared` asks whether the ledger is empty, and the
+                // undischarged-intent gap asks how much it still holds. Two reads would be two chances for
+                // them to disagree about the same file.
+                const openIntents = await openSessionIntents(deps, asString(args['sessionId']));
+                const changeUndeclared = await isChangeUndeclared(session.currentEditEpoch, () => Promise.resolve(openIntents));
+                const gaps = gapsForAction({
+                    pass: verdict.pass,
+                    proved: decision.verifiedReason === VerifiedReason.PROVED,
+                    changeUndeclared,
+                    source: actedSourceLabel,
+                    ref: asString(args['ref']),
+                    stateAsked: declaresState(until),
+                    stateUnwatched,
+                    // What the app DECLARED, so an under-instrumented one is told without having to be asked.
+                    hasCapabilities: session.hasCapabilities,
+                    // What the run still owes. A green that leaves this above zero is not the same as done.
+                    // MINUS the one this verdict is about to discharge.
+                    //
+                    // The discharge happens below, after the gaps are built, so a straight `openIntents.length`
+                    // counts the intent this very call proves. Measured live on the first drive: an inline
+                    // intent was declared, asserted and PROVED by the same verdict, and the result still said
+                    // "1 declared intent(s) are still unproved" while the ledger recorded it `proved`. A gap
+                    // that fires on the one path doing everything right is noise, and noise is what gets
+                    // filtered out — taking the honest gaps with it.
+                    openIntentCount: openIntents.filter((i) => !(intentId !== undefined && Verified.YES === decision.verified && i.id === intentId)).length,
+                    domMutated: (session.lastAct.effect().mutatedWithin ?? 0) > 0,
+                    signalsFired: actionSummary.signals.length,
+                    routeChanged: actionSummary.route !== undefined,
+                    routeSignalFired: actionSummary.signals.some((name) => name.startsWith('route')),
+                });
+                // The verdict IS the proof attempt, so a green one discharges the intent it was drawn for.
+                // Only a green: a red proved nothing, and `dischargeIntent` refuses an unbound intent anyway,
+                // so a bare settle leaves it open rather than collecting a proof nothing earned. The id is
+                // checked here rather than only inside the helper so a caller that declared no intent touches
+                // nothing at all, not even the clock.
+                if (intentId !== undefined && Verified.YES === decision.verified) {
+                    await dischargeInlineIntent(deps, asString(args['sessionId']), intentId, {
+                        verdictId: inlineVerdictId(ReticleTool.ACT_AND_WAIT, deps.now()),
+                        grade,
+                        at: deps.now(),
+                    });
+                }
+                verdictEffect = {
+                    claim: describeWaitTarget(until),
+                    verified: decision.verified,
+                    ...(actedSourceLabel === undefined ? {} : { source: actedSourceLabel }),
+                };
+                // Recorded on the session, so a later "am I done?" can answer with what is STILL missing
+                // rather than with everything that was ever missing. An empty list closes a gap, which is
+                // why it is noted rather than skipped.
+                noteSessionGaps(session, gaps);
                 return withControl(session, {
                     ...decision,
                     effect: leanActResult(actResult.result),
@@ -679,14 +812,15 @@ export const ACT_TOOLS = [
                     // 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
                     // most of the way to not reporting it at all.
-                    ...(verdict.pass || actedSource === undefined
-                        ? {}
-                        : { source: `${actedSource.file}:${String(actedSource.line)}` }),
+                    ...(verdict.pass || actedSourceLabel === undefined ? {} : { source: actedSourceLabel }),
                     trace,
                     ...(capsuleSaved === undefined ? {} : { capsuleSaved }),
                     // 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 }),
+                    summary: actionSummary,
+                    // What the APP did not tell Reticle, and the one change that would fix it. Reported only
+                    // where an absence made this very verdict weaker — never as a survey of the page.
+                    ...(gaps.length > 0 ? { instrumentationGaps: gaps } : {}),
                     // 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,
@@ -700,11 +834,12 @@ export const ACT_TOOLS = [
                     honesty,
                     ...(capsule === undefined ? {} : { capsule }),
                     since,
+                    ...(session.id === actedSessionId ? {} : { sessionId: session.id }),
                     ...healthEnvelope(session),
                 });
             }
             finally {
-                session.finishAction(undefined, settledOutcome, true === settledOutcome ? session.elapsed() - since : undefined);
+                acted.finishAction(verdictEffect, settledOutcome, true === settledOutcome ? acted.elapsed() - actedSince : undefined);
             }
         },
     },

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

@@ -0,0 +1,22 @@
+import type { Predicate } from '../events/predicate-schema.js';
+/**
+ * The `file:line` an ASSERTION is entitled to report — its own evidence, or nothing.
+ *
+ * `reticle_assert` and `reticle_wait_for` drive nothing, so the last act's source is whatever
+ * unrelated action ran before them. Journaling it made an assert on one component claim it had
+ * proven something about another, and an assert that matched nothing claim a location at all — a
+ * wrong file:line in front of an agent, persisted, and read back by `reticle_context` long after
+ * the turn that produced it.
+ *
+ * The one borrow that survives is the documented one, and only on a failure: a predicate with no DOM
+ * clause has no element to point at, and the handler that should have fired the missing signal or
+ * made the missing request lives with the control that was last driven. That is what the tools'
+ * output schemas describe, and it is a pointer to the code under test rather than a guess about
+ * which code this verdict was about.
+ */
+export declare function assertSource(facts: {
+    predicate: Predicate;
+    evidence: unknown;
+    pass: boolean;
+    lastActSource: string | undefined;
+}): string | undefined;

package/dist/tools/assert-source.js

@@ -0,0 +1,53 @@
+import { declaresDom } from '../events/predicate-asks.js';
+/**
+ * Where an assertion's OWN evidence is written, as `file:line`.
+ *
+ * The element descriptors an oracle returns already carry the nearest `data-reticle-source` the build
+ * plugin stamped, so a predicate that matched an element knows exactly where that element lives. It
+ * is only reported when every matched descriptor agrees: two loci and no way to choose is the same
+ * problem as no locus at all, and a guessed pointer costs the agent the trip AND leaves it further
+ * from the code.
+ *
+ * Near-miss evidence is deliberately NOT read. A near miss is a DIFFERENT element than the one the
+ * caller asked about, so its line is a suggestion dressed as a fact.
+ */
+function evidenceSource(evidence) {
+    if (!Array.isArray(evidence) || 0 === evidence.length)
+        return undefined;
+    let agreed;
+    for (const entry of evidence) {
+        if ('object' !== typeof entry || null === entry)
+            return undefined;
+        const found = entry.source;
+        if ('string' !== typeof found || 0 === found.length)
+            return undefined;
+        if (agreed === undefined)
+            agreed = found;
+        else if (agreed !== found)
+            return undefined;
+    }
+    return agreed;
+}
+/**
+ * The `file:line` an ASSERTION is entitled to report — its own evidence, or nothing.
+ *
+ * `reticle_assert` and `reticle_wait_for` drive nothing, so the last act's source is whatever
+ * unrelated action ran before them. Journaling it made an assert on one component claim it had
+ * proven something about another, and an assert that matched nothing claim a location at all — a
+ * wrong file:line in front of an agent, persisted, and read back by `reticle_context` long after
+ * the turn that produced it.
+ *
+ * The one borrow that survives is the documented one, and only on a failure: a predicate with no DOM
+ * clause has no element to point at, and the handler that should have fired the missing signal or
+ * made the missing request lives with the control that was last driven. That is what the tools'
+ * output schemas describe, and it is a pointer to the code under test rather than a guess about
+ * which code this verdict was about.
+ */
+export function assertSource(facts) {
+    const own = evidenceSource(facts.evidence);
+    if (own !== undefined)
+        return own;
+    if (facts.pass || declaresDom(facts.predicate))
+        return undefined;
+    return facts.lastActSource;
+}

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

@@ -1,3 +1,4 @@
+import type { InstrumentationGap, JournalVerdictEffect } from '@reticlehq/core';
 import type { Predicate } from '../events/predicate.js';
 import type { Session } from '../session/session.js';
 import { type Contradiction } from '../events/contradictions.js';
@@ -14,7 +15,12 @@ import { type Contradiction } from '../events/contradictions.js';
  * consult it. Asserting a moment earlier — while the POST was still open — is the same story with a
  * different name: `request-never-settled`, also unreported.
  */
-export declare function assertVerdict(session: Session, predicate: Predicate, pass: boolean, since: number, 
+export declare function assertVerdict(session: Session, predicate: Predicate, pass: boolean, 
+/**
+ * What the oracle actually looked at. The only thing this verdict is entitled to point at — see
+ * `assertSource`, which reads the matched element descriptors' own `file:line`.
+ */
+evidence: unknown, since: number, 
 /** Set when the assertion was never evaluated — see honesty/verified.ts. */
 inconclusive?: string, 
 /**
@@ -22,8 +28,21 @@ inconclusive?: string,
  * `reticle_wait_for` reach the same disconnect path as the act tools, and a verdict that blames
  * the app for a lost connection is no more honest on this route than on that one.
  */
-observationLost?: boolean): Promise<{
+observationLost?: boolean, 
+/**
+ * Set when code changed since the last verdict with nothing declaring what it was for. Decided by
+ * `isChangeUndeclared` at the call site, which is the only place that can reach the intent ledger —
+ * this path takes a session and no `deps`.
+ */
+changeUndeclared?: boolean): Promise<{
     decision: Record<string, unknown>;
     contradictions: Contradiction[];
     coverage: Record<string, unknown>;
+    gaps: InstrumentationGap[];
+    /**
+     * The bounded verdict, in the SAME shape `act_and_wait` writes into its journal action — so the
+     * journal holds one verdict shape rather than two and the run fold that reads it needs no second
+     * case. Built here because this is the one place that holds the typed decision and the predicate.
+     */
+    verdictEffect: JournalVerdictEffect;
 }>;

package/dist/tools/assert-verdict.js

@@ -1,6 +1,10 @@
 import { BlindSpotKind, CaptureLoss, PredicateKind } from '@reticlehq/core';
+import { gapsForAction } from '../honesty/instrumentation-gaps.js';
+import { noteSessionGaps } from '../honesty/gap-ledger.js';
+import { declaresState } from '../events/predicate-asks.js';
+import { isStateUnwatched } from '../honesty/blind-spots.js';
 import { findContradictions } from '../events/contradictions.js';
-import { declaredExpectations } from '../events/declared.js';
+import { declaredExpectations, declaresBodyIndependentChannel } 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';
@@ -9,6 +13,7 @@ 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';
+import { assertSource } from './assert-source.js';
 function absenceBlindSpotNote(predicate, spots) {
     if (predicate.kind !== 'element' || predicate.absent !== true)
         return undefined;
@@ -33,7 +38,12 @@ function absenceBlindSpotNote(predicate, spots) {
  * consult it. Asserting a moment earlier — while the POST was still open — is the same story with a
  * different name: `request-never-settled`, also unreported.
  */
-export async function assertVerdict(session, predicate, pass, since, 
+export async function assertVerdict(session, predicate, pass, 
+/**
+ * What the oracle actually looked at. The only thing this verdict is entitled to point at — see
+ * `assertSource`, which reads the matched element descriptors' own `file:line`.
+ */
+evidence, since, 
 /** Set when the assertion was never evaluated — see honesty/verified.ts. */
 inconclusive, 
 /**
@@ -41,7 +51,13 @@ inconclusive,
  * `reticle_wait_for` reach the same disconnect path as the act tools, and a verdict that blames
  * the app for a lost connection is no more honest on this route than on that one.
  */
-observationLost) {
+observationLost, 
+/**
+ * Set when code changed since the last verdict with nothing declaring what it was for. Decided by
+ * `isChangeUndeclared` at the call site, which is the only place that can reach the intent ledger —
+ * this path takes a session and no `deps`.
+ */
+changeUndeclared) {
     // Scope caveat, stated because it is a real limitation and not a bug: blind spots are tracked per
     // SESSION, not per assertion window, so a cross-origin iframe seen once marks every later verdict
     // in that session partial — including ones about a region it cannot affect. That errs toward
@@ -76,6 +92,8 @@ observationLost) {
     const declared = declaredExpectations(predicate);
     const contradictions = findContradictions(windowEvents, {
         prior,
+        currentDocumentId: session.currentDocumentId,
+        currentEditEpoch: session.currentEditEpoch,
         expectedFailures: declared.netFailures,
         renderProved: pass && declared.rendersContent,
         ...(actCursor !== undefined && actCursor >= since ? { actionSince: actCursor } : {}),
@@ -96,6 +114,7 @@ observationLost) {
         // 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,
+        ...(declaresBodyIndependentChannel(predicate) ? { independentOfBody: true } : {}),
         ...(inconclusive === undefined ? {} : { inconclusive }),
         ...(true === observationLost ? { observationLost: true } : {}),
         ...(absenceBlindSpot === undefined ? {} : { absenceBlindSpot }),
@@ -122,5 +141,41 @@ observationLost) {
             repeated: repeatedRequestLabels(windowEvents),
         },
     });
-    return { decision: decision, contradictions, coverage };
+    // The same rule the act path uses, fed by what THIS path knows. An assertion drives nothing, so
+    // only two of the four gates can fire here: a red with no remembered source to point at, and a
+    // state assertion against an app that registers no store.
+    const gaps = gapsForAction({
+        pass,
+        ...(changeUndeclared === undefined ? {} : { changeUndeclared }),
+        source: session.lastAct.source(),
+        stateAsked: declaresState(predicate),
+        stateUnwatched: isStateUnwatched(spots),
+        // What the app DECLARED, so an under-instrumented one is told without having to be asked.
+        hasCapabilities: session.hasCapabilities,
+        domMutated: false,
+        signalsFired: 0,
+        routeChanged: false,
+        routeSignalFired: false,
+    });
+    noteSessionGaps(session, gaps);
+    // The one file:line this verdict is entitled to: its own evidence, or — for a failure with no DOM
+    // clause to point at — the control last driven. Returned so the RESPONSE can echo the same value
+    // the journal keeps; one verdict must never carry two different pointers.
+    const source = assertSource({
+        predicate,
+        evidence,
+        pass,
+        lastActSource: session.lastAct.source(),
+    });
+    return {
+        decision: decision,
+        contradictions,
+        coverage,
+        gaps,
+        verdictEffect: {
+            claim: describeWaitTarget(predicate),
+            verified: decision.verified,
+            ...(source === undefined ? {} : { source }),
+        },
+    };
 }

package/dist/tools/browser-tools.js

@@ -88,24 +88,4 @@ export const BROWSER_TOOLS = [
             }
         },
     },
-    {
-        name: ReticleTool.REFRESH,
-        description: 'Reload the connected browser tab. Pass { hard: true } to bypass the browser cache (equivalent to Cmd+Shift+R). The SDK reconnects automatically after the reload.',
-        inputSchema: {
-            hard: z
-                .boolean()
-                .optional()
-                .describe('Set true to bypass the browser cache. Default: false (normal reload).'),
-            ...sessionIdShape,
-        },
-        outputSchema: {
-            ok: z.boolean(),
-        },
-        handler: async (deps, args) => {
-            await commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.REFRESH, {
-                hard: true === args['hard'],
-            });
-            return { ok: true };
-        },
-    },
 ];