@reticlehq/server 3.2.0 → 3.4.0

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

@@ -3,23 +3,8 @@ 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 } from '../../language/flows/replay.js';
-/**
- * The pathname of a session's live url, or undefined when it has none yet.
- *
- * Pathname rather than the whole url, because that is what `startPath` is compared against and what
- * a hash-routed app makes meaningless in the document location — see routeOfEvent.
- */
-function pathOf(url) {
-    if (url === undefined)
-        return undefined;
-    try {
-        return new URL(url).pathname;
-    }
-    catch {
-        return undefined;
-    }
-}
+import { captureAct, captureVerdictedAct, pathOf } 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, } from '@reticlehq/core';
 import { leanActResult, mutatedWithin } from './act/act-view.js';
 import { ReticleTool } from '@reticlehq/core';
@@ -37,12 +22,12 @@ import { intentDebt, openSessionIntents } from '../../memory/intent/open-intents
 import { dischargeInlineIntent, inlineVerdictId, linkInlineIntent, } from '../../memory/intent/inline-intent.js';
 import { declaresState } from '@reticlehq/engine/question/predicate/predicate-asks.js';
 import { isStateUnwatched } from '@reticlehq/engine/evidence/blind-spots.js';
-import { inFlightRequestLabels, repeatedRequestLabels, waitForInFlight, } from './act/settle-in-flight.js';
-import { waitForReaction } from './act/react-grace.js';
+import { inFlightRequestLabels, repeatedRequestLabels } from './act/settle-in-flight.js';
+import { finishAfterMatch } from './act/after-match.js';
+import { noteProved } from './act/proved-controls.js';
 import { decideVerified } from '@reticlehq/engine/evidence/verified.js';
 import { honestyForVerdict } from '@reticlehq/engine/evidence/honesty.js';
 import { declaredExpectations, declaresBodyIndependentChannel, } from '@reticlehq/engine/question/declared.js';
-import { readsDomState, alreadyTrueHiddenMatch as alreadyTrueHiddenMatchOf, } from '@reticlehq/engine/evidence/already-true.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';
@@ -52,7 +37,8 @@ import { absenceBlindSpotNote, buildCoverageStatement, blindSpotsFromState, tran
 import { acceptedWriteLabels } from '@reticlehq/engine/evidence/accepted-write.js';
 import { unreadWriteLabels } from '@reticlehq/engine/evidence/unread-outcome.js';
 import { evaluatePredicate, waitForPredicate, provenExpectedLinks, PredicateSchema, } from '@reticlehq/engine/question/predicate/predicate.js';
-import { healthEnvelope, refuseIfThrottled } from '../../portal/session/session-health.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';
 import { asNumber, asRecord, asString } from '@reticlehq/core';
 import { sourceOf } from './tools-helpers.js';
@@ -64,6 +50,7 @@ import { asActionType, gradeOf } from './act/act-helpers.js';
 import { resolveActTarget } from './act/act-target.js';
 import { tryRealInput, rewriteUploadArgs, HOVER_NEEDS_POINTER_MSG } from './real-input-attempt.js';
 import { gradeOfPredicate } from './assert/assert-grade.js';
+import { readAlreadyTrue } from './act/already-true.js';
 /**
  * Narrow the wire's `action` to a real ActionType, or undefined.
  *
@@ -253,6 +240,7 @@ export const ACT_TOOLS = [
                 });
             }
             finally {
+                deps.recordings.markEnded(pathOf(session.url));
                 // Close the window on every exit (settle or throw), recording the action + settle outcome.
                 session.finishAction(undefined, settledOutcome, true === settledOutcome ? session.elapsed() - since : undefined);
             }
@@ -285,7 +273,7 @@ export const ACT_TOOLS = [
                 .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. 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).'),
+            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
                 .optional()
@@ -295,9 +283,11 @@ export const ACT_TOOLS = [
                 .optional()
                 .describe('Throw if the tab is throttled. Default: false.'),
             intent: intentArg,
+            durable: durableArg,
             ...sessionIdShape,
         },
         outputSchema: {
+            durable: durableOutput,
             effect: z
                 .unknown()
                 .describe('The reticle_act result (dispatched, settled, inputMode, etc.).'),
@@ -428,22 +418,13 @@ export const ACT_TOOLS = [
             // 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
-            // is otherwise unfalsifiable. See engine/src/evidence/already-true.ts.
-            const alreadyTruePrecheck = until !== undefined && readsDomState(until)
-                ? await evaluatePredicate(session, until, since, false)
-                : undefined;
-            const alreadyTrue = alreadyTruePrecheck?.pass ?? false;
+            // 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);
-            // #889: the pre-check evidence is already in hand — cheap to also ask whether that match was
-            // against something hidden, so the already_true message can name it instead of leaving the
-            // agent to re-derive "was this actually showing?" from nothing.
-            const alreadyTrueHiddenMatch = alreadyTrue && until !== undefined
-                ? alreadyTrueHiddenMatchOf(until, alreadyTruePrecheck?.evidence)
-                : false;
+            // Recorded in `finally`, once the verdict is known — see captureVerdictedAct.
+            let dispatched;
+            let recordedVerdict;
             try {
                 // actCommand is the single interception point for upload+path rewrite.
                 //
@@ -461,7 +442,7 @@ export const ACT_TOOLS = [
                 if (actResult !== null) {
                     if (!actResult.ok)
                         throw new Error(actResult.error ?? 'act failed');
-                    captureAct(deps.recordings, args, actResult.result, routeBeforeWait);
+                    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
                     // mutation count.
@@ -472,8 +453,8 @@ export const ACT_TOOLS = [
                 let verdict = null === actResult
                     ? { pass: false, observationLost: true }
                     : timeout > 0
-                        ? await waitForPredicate(session, until, timeout, since)
-                        : await evaluatePredicate(session, until, since);
+                        ? await waitForPredicate(session, until, timeout, since, baselines)
+                        : await evaluatePredicate(session, until, since, true, baselines);
                 // The SDK may have gone away mid-act — see act-observation.ts.
                 const followed = await followLostObservation({
                     sessions: deps.sessions,
@@ -481,40 +462,18 @@ export const ACT_TOOLS = [
                     verdict,
                     timeout,
                     predicateStarted,
-                    reevaluate: (next, budget) => waitForPredicate(next, until, budget, 0),
+                    reevaluate: (next, budget) => waitForPredicate(next, until, budget, 0, baselines),
                 });
                 if (followed.followed)
                     since = 0;
                 session = followed.session;
                 verdict = followed.verdict;
-                // The predicate resolves the INSTANT it holds, which on an optimistically-navigating app is
-                // while the write is still in flight — so the verdict was taken over a window the app had not
-                // finished, and came back `unknown / unsettled` asking the CALLER to re-check. A login that
-                // genuinely succeeded returned at 492ms of an 8000ms budget with every corroborating channel
-                // agreeing. Spend the rest of the budget the caller already granted.
-                //
-                // This decides nothing: it waits for the answer instead of guessing at it. A response that
-                // arrives as a FAILURE still contradicts — and now arrives INSIDE the window, where the
-                // detector can see it at all — while a request still open when the budget genuinely runs out
-                // reports unsettled exactly as before, an honest limit rather than an early exit. Costs
-                // nothing on the common path, where no request is in flight.
+                // After a match, let the app finish before the window closes — see act/after-match.ts.
                 if (verdict.pass && timeout > 0) {
-                    const sleep = {
-                        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
-                    };
-                    const spent = () => timeout - (session.elapsed() - predicateStarted);
-                    await waitForInFlight(session, since, spent(), sleep);
-                    // Waiting for the response moved the hazard rather than removing it: the response now lands
-                    // inside the window BY DESIGN, and the app's re-render happens a task or two later. Close
-                    // the window in that gap and every channel agrees the app took a successful write and did
-                    // nothing — `response-ignored`, i.e. `verified:"no"` on a correct app, produced entirely by
-                    // where we stopped looking. A false accusation is the more damaging direction of error for
-                    // a verification tool: it sends someone to fix code that is not broken.
-                    //
-                    // So the response is not the end of the window; the app's REACTION to it is. Paid only in
-                    // the shape that would otherwise be accused — a successful mutating write with nothing
-                    // moved after it — and short enough that a genuinely dropped response is still reported.
-                    await waitForReaction(session, since, spent(), sleep);
+                    const left = () => timeout - (session.elapsed() - predicateStarted);
+                    const reverted = await finishAfterMatch(session, until, since, baselines, left);
+                    if (reverted !== undefined)
+                        verdict = { pass: false, failureReason: reverted, observed: reverted };
                 }
                 const r = asRecord(actResult?.result);
                 if ('boolean' === typeof r['settled'])
@@ -654,17 +613,17 @@ export const ACT_TOOLS = [
                     currentDocumentId: session.currentDocumentId,
                     currentEditEpoch: session.currentEditEpoch,
                     appOrigin: session.url,
+                    background: session.background,
                 });
                 // The single field an agent reads. Everything below it is the evidence it was derived from;
                 // this is the only one that has to be interpreted, and now it interprets itself.
                 const outcomePending = acceptedWriteLabels(windowEvents);
                 const outcomeUnread = unreadWriteLabels(windowEvents);
-                const stillInFlight = inFlightRequestLabels(windowEvents);
-                const decision = decideVerified({
+                const stillInFlight = inFlightRequestLabels(windowEvents, session.url, session.background);
+                const { decision, durable } = await withDurability(args['durable'], until, decideVerified({
                     pass: verdict.pass,
-                    // So the unread-body remedy can check it applies to THIS page. Threaded rather than
-                    // looked up inside decideVerified, which is pure and has no session.
-                    ...(session.sdkVersion === undefined ? {} : { sdkVersion: session.sdkVersion }),
+                    // Threaded rather than looked up: decideVerified is pure and has no session.
+                    ...sessionVerdictFacts(session),
                     // The caller NAMED the consequence rather than defaulting to "wait for idle". A
                     // declaration made before the action is what this tool sells, and idle-settlement was
                     // overriding it — see `declaredConsequence`. An explicit `{ kind: "settled" }` is not a
@@ -701,7 +660,9 @@ export const ACT_TOOLS = [
                         repeated: repeatedRequestLabels(windowEvents),
                     },
                     ...(namedNetIsInFlight(until, stillInFlight) ? { namedRequestInFlight: true } : {}),
-                });
+                }), (part) => reloadAndRecheck(deps, session, part, timeout));
+                recordedVerdict = String(decision.verified);
+                noteProved(session, recordedVerdict, actResult?.result);
                 // 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, {
@@ -770,6 +731,16 @@ export const ACT_TOOLS = [
                     // which is why the two are recorded apart rather than assumed alike.
                     declaredBeforeActing: true,
                     grade: gradeOfPredicate(until),
+                    // What the declared consequence READ. The run fold has only the journal, so a kind absent
+                    // here was being invented there as `element`. Same field, same reason, on the assert path.
+                    kind: until.kind,
+                    // The deciding clause, kept — and it was NOT, on this path, the commonest one. `unknown`
+                    // alone cannot tell an outcome that has not arrived from a capture that could not be
+                    // read, so a fold over the journal saw a verdict it could not attribute, and the
+                    // attribution is the only part of an `unknown` a reader can act on. The comment above
+                    // says "same field, same reason, on the assert path" and was half true. Found by the
+                    // session gap summary, whose `undecidedBy` was empty for every unknown this tool made.
+                    reason: decision.verifiedReason,
                 };
                 // 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
@@ -777,6 +748,8 @@ export const ACT_TOOLS = [
                 noteSessionGaps(session, gaps);
                 return withControl(session, {
                     ...decision,
+                    // WHAT was already true, not only that something was (4.1) — see act/already-true.ts.
+                    ...(alreadyTrueEvidence === undefined ? {} : { alreadyTrueEvidence }),
                     // 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) }),
@@ -817,16 +790,20 @@ export const ACT_TOOLS = [
                     // agent cannot miss it by not asking. Omitted entirely when clean, so a healthy action
                     // pays nothing.
                     ...(contradictions.length > 0 ? { contradictions } : {}),
+                    ...(durable === undefined ? {} : { durable }),
                     honesty: honestyForVerdict(String(decision.verified), honesty),
                     // Without its summary: it is byte-identical to `summary` two fields up. See wireCapsule.
                     ...(capsule === undefined ? {} : { capsule: wireCapsule(capsule) }),
                     ...(0 === greenRadius.length ? {} : { blastRadius: greenRadius }),
                     since,
                     ...(session.id === actedSessionId ? {} : { sessionId: session.id }),
-                    ...healthEnvelope(session),
+                    ...healthEnvelope(currentOf(deps.sessions, session)),
                 });
             }
             finally {
+                if (dispatched !== undefined)
+                    captureVerdictedAct(deps.recordings, args, dispatched.result, routeBeforeWait, recordedVerdict);
+                deps.recordings.markEnded(pathOf(currentOf(deps.sessions, session).url));
                 acted.finishAction(verdictEffect, settledOutcome, true === settledOutcome ? acted.elapsed() - actedSince : undefined);
             }
         },

package/dist/surface/tools/args/numeric-bounds.d.ts

@@ -31,8 +31,6 @@ export declare const MAX_BLOCKING_WAIT_MS: number;
  * in the name of bounding one that never worked.
  */
 export declare const MAX_STATE_DEPTH = 256;
-/** Scroll-to-find steps. Default is 20; hundreds is searching, thousands is a hang. */
-export declare const MAX_SCROLLS = 200;
 /** Viewport CSS px — matches the clamp the handler already applied, now as a refusal. */
 export declare const MIN_VIEWPORT_PX = 64;
 export declare const MAX_VIEWPORT_PX = 10000;
@@ -45,6 +43,21 @@ export declare const cursorSchema: z.ZodNumber;
  * A wait budget in ms. 0 means evaluate now (documented on assert). Negative cannot be honoured.
  */
 export declare const timeoutMsSchema: z.ZodNumber;
+/**
+ * `reticle_wait_for`'s budget, which may exceed one call: it waits at most MAX_BLOCKING_WAIT_MS per
+ * call and hands back `resume_ms` for the rest (#601, from #635).
+ */
+export declare const waitForTimeoutMsSchema: z.ZodNumber;
+/**
+ * What is left of a wait that stopped at the per-call limit, or undefined when there is nothing to
+ * resume: the predicate held, the whole budget fit in this call, or the wait ended for a reason
+ * waiting longer cannot change (the page went away, or the read could not be made).
+ */
+export declare function resumeAfter(requestedMs: number, perCallMs: number, verdict: {
+    pass: boolean;
+    observationLost?: boolean;
+    inconclusive?: string;
+}): number | undefined;
 /**
  * A count / cap. 0 means "return none", which is a real request. Negative is not.
  * Capped at the ring-buffer size so a `limit: 1e9` cannot pretend the buffer is larger than it is.

package/dist/surface/tools/args/numeric-bounds.js

@@ -38,8 +38,8 @@ export const MAX_TIMEOUT_MS = 120_000;
  *
  * This does not make long waits possible, and is not meant to — it makes the ADVERTISED bound one
  * that can actually be honoured. A caller that genuinely needs to outlast this polls: several short
- * waits, each of which returns a verdict. See #601 for the bounded-wait cursor that would let one
- * call do it properly.
+ * waits, each of which returns a verdict. `reticle_wait_for` does that for the caller: see
+ * `waitForTimeoutMsSchema` and `resumeAfter`.
  */
 const MCP_SDK_DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
 export const MAX_BLOCKING_WAIT_MS = MCP_SDK_DEFAULT_REQUEST_TIMEOUT_MS - 5_000;
@@ -54,7 +54,7 @@ export const MAX_STATE_DEPTH = 256;
 /** A crawl that clicks forever is not a bound. */
 const MAX_CRAWL_STEPS = 500;
 /** Scroll-to-find steps. Default is 20; hundreds is searching, thousands is a hang. */
-export const MAX_SCROLLS = 200;
+const MAX_SCROLLS = 200;
 /** Fake-clock jump. One day of timers is a test; a billion ms is not. */
 const MAX_ADVANCE_MS = 86_400_000;
 /** Presenter idle window. One hour is a slow app; larger values never fire. */
@@ -71,6 +71,33 @@ export const cursorSchema = z.number().finite().int().nonnegative();
  * A wait budget in ms. 0 means evaluate now (documented on assert). Negative cannot be honoured.
  */
 export const timeoutMsSchema = z.number().finite().int().nonnegative().max(MAX_BLOCKING_WAIT_MS);
+/**
+ * The longest `reticle_wait_for` accepts, across as many calls as it takes. Ten minutes is a slow
+ * build or a queued job; an hour is a hang somebody forgot about.
+ */
+const MAX_RESUMABLE_WAIT_MS = 600_000;
+/**
+ * `reticle_wait_for`'s budget, which may exceed one call: it waits at most MAX_BLOCKING_WAIT_MS per
+ * call and hands back `resume_ms` for the rest (#601, from #635).
+ */
+export const waitForTimeoutMsSchema = z
+    .number()
+    .finite()
+    .int()
+    .nonnegative()
+    .max(MAX_RESUMABLE_WAIT_MS);
+/**
+ * What is left of a wait that stopped at the per-call limit, or undefined when there is nothing to
+ * resume: the predicate held, the whole budget fit in this call, or the wait ended for a reason
+ * waiting longer cannot change (the page went away, or the read could not be made).
+ */
+export function resumeAfter(requestedMs, perCallMs, verdict) {
+    if (verdict.pass || true === verdict.observationLost || verdict.inconclusive !== undefined) {
+        return undefined;
+    }
+    const left = requestedMs - perCallMs;
+    return left > 0 ? left : undefined;
+}
 /**
  * A count / cap. 0 means "return none", which is a real request. Negative is not.
  * Capped at the ring-buffer size so a `limit: 1e9` cannot pretend the buffer is larger than it is.

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

@@ -10,7 +10,7 @@
  *
  * Pure: no IO, no clock.
  */
-import { isConsequenceKind, isPresenceKind, PredicateKind } from '@reticlehq/core';
+import { compareSourceClauses, isConsequenceKind, isPresenceKind, PredicateKind, } from '@reticlehq/core';
 import { HonestyGrade, strongerGrade, weakerGrade } from '@reticlehq/engine/evidence/honesty.js';
 export const PRESENCE_ONLY_ADVICE = 'This predicate only checks element/text presence, not an observable consequence. A locator healed to the wrong element (or a stale render) can satisfy it while the feature is broken. Prefer a { signal } or { net } assertion (or allOf it with one) so green means the feature actually worked.';
 function walk(predicate, negated = false) {
@@ -27,6 +27,14 @@ function walk(predicate, negated = false) {
     // never matched anything in the first place. Negation makes a presence check weaker, not stronger.
     if (PredicateKind.NOT === predicate.kind)
         return walk(predicate.predicate, true);
+    // A comparison grades as what its sides read: with a net/signal/state side it relates the page to
+    // the app's own record, which a wrong locator cannot fake; text against text is two readings of
+    // the same DOM. Its text side is always a content check, so it never counts as bare presence
+    // unless negated.
+    if (PredicateKind.COMPARE === predicate.kind) {
+        const consequence = compareSourceClauses(predicate).some((c) => isConsequenceKind(c.kind));
+        return { consequence, presence: !consequence && negated };
+    }
     // Leaf: classify against the single source of truth in core. Kinds that are neither consequence
     // nor presence (route/console/settled/animation) correctly return false for both.
     return {
@@ -109,17 +117,32 @@ export function gradeOfPredicate(predicate) {
         // verdict that proved only presence report `signal`, and a `minGrade: net` gate would trust it.
         case PredicateKind.ANY_OF:
             return combine(predicate.predicates, weakerGrade);
+        // Both sides had to be read and agree, so it proves as much as its stronger side.
+        case PredicateKind.COMPARE:
+            return combine(compareSourceClauses(predicate), strongerGrade);
         // Everything else, `not` included: an absence claim is satisfied trivially by a locator that
         // never matched anything, which is the argument `walk` already makes about negation.
         default:
             return HonestyGrade.PRESENCE;
     }
 }
-/** Fold a combinator's branches on the ladder. No branches proves nothing, so it stays at the floor. */
+/**
+ * Fold a combinator's branches on the ladder. No branches proves nothing, so it stays at the floor.
+ *
+ * The floor is `NONE`, not `PRESENCE`. This sentence has been here since the function was written
+ * and the code returned one rung above it, which is the entire defect: `VACUOUS_GRADE`
+ * (`engine/src/evidence/verified.ts`) fires on `NONE`, so an empty combinator graded `PRESENCE`
+ * walked past the one guard whose job is refusing a green that rests on nothing — and reported
+ * `verified: "yes"` for a drive that asserted nothing at all.
+ *
+ * The schema refuses an empty combinator now, so this is the second defence rather than the only
+ * one. It is kept because the two stop different things: the schema stops it ENTERING through the
+ * documented door, and this stops it COUNTING if it is ever constructed rather than parsed.
+ */
 function combine(branches, pick) {
     const grades = branches.map(gradeOfPredicate);
     const first = grades[0];
     if (first === undefined)
-        return HonestyGrade.PRESENCE;
+        return HonestyGrade.NONE;
     return grades.reduce(pick, first);
 }

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

@@ -1,4 +1,5 @@
-import { CaptureLoss, channelsRead, PredicateKind } from '@reticlehq/core';
+import { CaptureLoss, channelsReadBy, PredicateKind } from '@reticlehq/core';
+import { sessionVerdictFacts } from '../../../portal/session/session-verdict-facts.js';
 import { gapsForAction } from '@reticlehq/engine/evidence/instrumentation-gaps.js';
 import { noteSessionGaps } from '@reticlehq/engine/evidence/gap-ledger.js';
 import { declaresState } from '@reticlehq/engine/question/predicate/predicate-asks.js';
@@ -15,6 +16,7 @@ import { describeWaitTarget, namedNetIsInFlight } from '@reticlehq/engine/eviden
 import { inFlightRequestLabels, repeatedRequestLabels, } from '../act/settle-in-flight.js';
 import { gradeOfPredicate } from './assert-grade.js';
 import { assertSource } from './assert-source.js';
+import { VerdictAttribution, verdictAttributionOf } from '@reticlehq/core';
 /**
  * The honesty verdict for a plain `reticle_assert`.
  *
@@ -85,6 +87,7 @@ changeUndeclared) {
         currentDocumentId: session.currentDocumentId,
         currentEditEpoch: session.currentEditEpoch,
         appOrigin: session.url,
+        background: session.background,
         expectedFailures: declared.netFailures,
         namedNetUrls: declared.netUrls,
         renderProved: pass && declared.rendersContent,
@@ -114,7 +117,7 @@ changeUndeclared) {
     const impeachingNotes = [impeaching.note, gap, ...crashedRuleNotes()].filter((n) => n !== undefined);
     const outcomePending = acceptedWriteLabels(windowEvents);
     const outcomeUnread = unreadWriteLabels(windowEvents);
-    const stillInFlight = inFlightRequestLabels(windowEvents);
+    const stillInFlight = inFlightRequestLabels(windowEvents, session.url, session.background);
     const effectiveInconclusive = inconclusive ?? (!pass ? session.preconditionFailure?.() : undefined);
     /**
      * Does a green here rest on the window having been COMPLETE?
@@ -145,11 +148,10 @@ changeUndeclared) {
         // first clause, and one this implementation could not run until the page started declaring.
         // Both halves are conditional on purpose: an SDK too old to declare sends nothing, and
         // treating that silence as an empty set would refuse every claim from every older page.
-        channelsRead: channelsRead(predicate.kind),
+        channelsRead: channelsReadBy(predicate),
         ...(session.channels === undefined ? {} : { channelsObservable: session.channels }),
-        // So the unread-body remedy can check it applies to THIS page. Threaded rather than
-        // looked up inside decideVerified, which is pure and has no session.
-        ...(session.sdkVersion === undefined ? {} : { sdkVersion: session.sdkVersion }),
+        // Threaded rather than looked up: decideVerified is pure and has no session.
+        ...sessionVerdictFacts(session),
         // Same rule as the act path: the caller named a consequence, so a settlement-only finding must
         // not override it. A fix that lived on one half of the verdict surface would leave the other
         // half broken, and this is the tool agents call most.
@@ -217,6 +219,8 @@ changeUndeclared) {
         pass,
         lastActSource: session.lastAct.source(),
     });
+    // Who can act on this verdict, derived from the clause that decided it — see `attributedTo` below.
+    const attributedTo = verdictAttributionOf(decision.verifiedReason);
     return {
         decision: decision,
         contradictions,
@@ -226,6 +230,9 @@ changeUndeclared) {
             claim: describeWaitTarget(predicate),
             verified: decision.verified,
             ...(source === undefined ? {} : { source }),
+            // What answering this claim READ. Known here and nowhere later: a run folded from the journal
+            // has only what the journal kept, and without this it stamped `element` on every check.
+            kind: predicate.kind,
             // The three facts that make a verdict something other than a pass/fail line. All three were
             // known right here and none of them survived into the durable record, so nothing downstream
             // could report them however well this moment understood them.
@@ -240,6 +247,25 @@ changeUndeclared) {
             // arrived from a capture that could not be read, and only the first is worth asking about
             // again -- which is what makes a later answer a CORRECTION rather than a second opinion.
             reason: decision.verifiedReason,
+            /*
+             * WHOSE problem it is, in four values, finishing the sentence above.
+             *
+             * The reason names the deciding clause; this names who can act on it, which for an `unknown`
+             * is the only question the reader has. `environment` resolves by waiting, `could-not-see` by
+             * looking again with better coverage, `harness` by fixing Reticle or the call, and `code` is
+             * the only one that means go and change the app. Omitted on a proof, which has no owner.
+             *
+             * Derived here rather than inside the verdict: it is a pure function of a reason the engine
+             * already returns, and `core-coupling-only-shrinks` caps what the engine may borrow from core.
+             *
+             * Named `attributedTo`, not `attribution`, because two other things already carry that word:
+             * `honesty.attribution` a few lines up ("what the grade is attributed to" — the window), and
+             * `BugAttribution` in telemetry ("we found a defect, whose defect is it?"). Three meanings on
+             * one noun is how a reader ends up acting on the wrong one.
+             */
+            ...(attributedTo === undefined || VerdictAttribution.NONE === attributedTo
+                ? {}
+                : { attributedTo }),
             grade: gradeOfPredicate(predicate),
             couldNotSee: spots.map((spot) => spot.kind),
         },

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

@@ -1,7 +1,7 @@
 import { carryReticleIdentity } from './lease-tools.js';
 import { z } from 'zod';
 import { navigateResult } from './act/navigation/navigate-result.js';
-import { awaitArrival, idsAtTarget, ARRIVAL_TIMEOUT_MS, } from './act/navigation/navigate-arrival.js';
+import { absoluteTarget, awaitArrival, idsAtTarget, ARRIVAL_TIMEOUT_MS, } from './act/navigation/navigate-arrival.js';
 import { reloadResult } from './act/navigation/reload-result.js';
 import { waitForReconnect, RELOAD_RECONNECT_TIMEOUT_MS, } from '../../portal/session/session-reconnect.js';
 import { ReticleCommand } from '@reticlehq/core';
@@ -13,7 +13,7 @@ export const BROWSER_TOOLS = [
     {
         name: ReticleTool.NAVIGATE,
         example: { url: '/settings' },
-        description: 'Navigate the connected browser tab to a URL, or reload it in place with { reload: true } (add { hard: true } to bypass the cache). `ok` means the navigation was DISPATCHED — the SDK is torn down by the navigation, so the page itself cannot report on it. The daemon then waits up to `timeout_ms` (default 5000) for the SDK to reconnect: `confirmed:true` with a new `sessionId` means the page arrived and you can act immediately. `confirmed:false` means it did not arrive within that window (reported as `waitedMs`) — the page may be slow, uninstrumented, or not there. A slow SPA can take 30-60s to reattach: raise `timeout_ms` rather than polling reticle_sessions.',
+        description: 'Navigate the connected browser tab to a URL, or reload it in place with { reload: true } (add { hard: true } to bypass the cache). `ok` means the navigation was DISPATCHED — the SDK is torn down by the navigation, so the old page cannot report on it. The daemon then waits up to `timeout_ms` (default 5000) for the SDK to reconnect. `confirmed:true` with a `sessionId` means the requested page arrived and you can act immediately. `confirmed:false` with `landedOn` means the navigation arrived but the app landed at another URL, such as an authentication or route-guard redirect; use `landedOn` to understand where the browser actually ended up. `confirmed:false` without `landedOn` means the target was not observed within the wait window; a slow app may still be on its way, so increase `timeout_ms` when appropriate.',
         inputSchema: {
             url: z.string().optional().describe('The URL to navigate to. Omit when using reload.'),
             reload: z
@@ -38,6 +38,10 @@ export const BROWSER_TOOLS = [
             confirmed: z.boolean().optional(),
             /** The session the SDK reconnected as, when arrival was confirmed — it is a NEW id. */
             sessionId: z.string().optional(),
+            /**
+             * The URL where the navigated document landed when it differs from the requested target.
+             */
+            landedOn: z.string().optional(),
             /**
              * On confirmed:false — the budget (ms) that expired without the page coming back. Says which
              * of "Reticle stopped waiting" and "the page never came back" you are looking at.
@@ -58,6 +62,7 @@ export const BROWSER_TOOLS = [
                 // back past this point. Reported from the field as an assertion whose clauses all passed
                 // coming back `contradicted` by hundreds of 500s against resources that were already gone.
                 before.lastAct.markNavigated(before.elapsed());
+                deps.recordings.markNavigated();
                 await commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.REFRESH, {
                     hard: true === args['hard'],
                 });
@@ -89,12 +94,14 @@ export const BROWSER_TOOLS = [
             // Sampled BEFORE dispatch, because that is the only moment it can be known. A session already
             // sitting on the target is not evidence that THIS navigation arrived — and the arrival scan,
             // which reads whatever is at the target afterwards, cannot tell the two apart on its own.
-            const priorIds = idsAtTarget(deps.sessions, url);
+            const target = absoluteTarget(url, session.url);
+            const priorIds = idsAtTarget(deps.sessions, target);
             session.beginAction(ReticleTool.NAVIGATE, { url });
             // Same floor as the reload path above, for the same reason: going to a new URL replaces the
             // document just as thoroughly. `beginAction` attributes events to this action; it does not move
             // the window a later assert judges over, and those are two different jobs.
             session.lastAct.markNavigated(session.elapsed());
+            deps.recordings.markNavigated();
             try {
                 const result = (await commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.NAVIGATE, { url }));
                 // `ok` is the browser accepting the instruction, not the page arriving — see navigate-result.
@@ -103,7 +110,13 @@ export const BROWSER_TOOLS = [
                 // reticle_sessions itself. A refusal skips the wait: there is nothing to wait FOR.
                 const timeoutMs = asNumber(args['timeout_ms']) ?? ARRIVAL_TIMEOUT_MS;
                 const arrival = true === result.ok
-                    ? await awaitArrival(deps.sessions, url, { navigatedId: session.id, priorIds }, timeoutMs)
+                    ? await awaitArrival(deps.sessions, target, {
+                        // Keep the original Session object and URL so arrival detection can distinguish
+                        // an in-progress navigation from a document that arrived somewhere else.
+                        navigatedSession: session,
+                        navigatedFrom: session.url,
+                        priorIds,
+                    }, timeoutMs)
                     : null;
                 return navigateResult(result, arrival, timeoutMs);
             }

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

@@ -10,6 +10,7 @@ import { ReticleTool } from '@reticlehq/core';
 import { asString } from '@reticlehq/core';
 import { exercisedCount } from './gaps/coverage-identity.js';
 import { commandOrThrow, sessionIdShape } from './tool-kit.js';
+import { foldAppCoverage } from '../../features/exhaust/app-coverage.js';
 /**
  * `reticle_coverage` — which interactive controls this session has driven, and which it has not.
  *
@@ -69,8 +70,17 @@ export function buildCoverageTools(toolNames) {
             name: ReticleTool.COVERAGE,
             description: 'Which interactive controls you have driven this session, and which you have NOT. Returns { total, exercised, untouched:[{ref,label}], alsoDroveGone? } over the controls currently on the page. Use it to decide whether verification is finished: an untouched list that still holds the controls your change affects means you are not done. This is about what you did not TOUCH — distinct from the `coverage` field on an action result, which reports what the layer could not SEE.',
             example: {},
-            inputSchema: { ...sessionIdShape },
+            inputSchema: {
+                app: z
+                    .boolean()
+                    .optional()
+                    .describe('Also fold into the app-wide ledger; returns `app.levels`.'),
+                ...sessionIdShape,
+            },
             outputSchema: {
+                // The app-wide ledger — see features/exhaust/ledger.ts. Loose: run-only, and the levels
+                // carry their own shape.
+                app: z.record(z.unknown()).optional(),
                 total: z.number(),
                 exercised: z.number(),
                 untouched: z.array(z.object({ ref: z.string(), label: z.string() })),
@@ -171,6 +181,22 @@ export function buildCoverageTools(toolNames) {
                     ...(regressed === undefined ? {} : { observabilityRegressed: regressed }),
                     featureUse,
                     toolHitRate,
+                    ...(true === args['app']
+                        ? {
+                            app: await foldAppCoverage({
+                                fs: deps.fs,
+                                reticleRoot: sessionRoot(deps, sessionId),
+                                seen: parseControls(tree).map((c) => c.label),
+                                session,
+                                now: deps.now,
+                                ...(deps.realInput?.takeCodeCoverage === undefined
+                                    ? {}
+                                    : {
+                                        takeCode: (url) => deps.realInput?.takeCodeCoverage?.(url) ?? Promise.resolve(undefined),
+                                    }),
+                            }),
+                        }
+                        : {}),
                 };
             },
         },