@reticlehq/server 3.2.0 → 3.3.0

package/dist/surface/tools/act/settle-in-flight.js

@@ -27,7 +27,7 @@
  *   - still in flight when the budget genuinely runs out → `unsettled`, as before, but now an honest
  *     limit instead of an early exit.
  */
-import { EventType, NetInitiator, isDevToolingUrl } from '@reticlehq/core';
+import { EventType, NetInitiator, isDevToolingUrl, isForeignTraffic } from '@reticlehq/core';
 /**
  * The dev toolchain talking about ITSELF is not the app finishing its work.
  *
@@ -37,6 +37,25 @@ import { EventType, NetInitiator, isDevToolingUrl } from '@reticlehq/core';
  * was graded on the strength of a Next webpack hot-update the same payload printed as ignored.
  */
 const isDevTooling = (data) => isDevToolingUrl('string' === typeof data['url'] ? data['url'] : undefined);
+/**
+ * Somebody else's host is not the app finishing its work.
+ *
+ * The comment above makes this argument for dev tooling and it holds identically here:
+ * `splitForeignTraffic` drops dev tooling AND third-party traffic, and this file dropped only the
+ * first — so the exclusion stayed cosmetic exactly where it decides a verdict, for the other half.
+ *
+ * Reported from the field repeatedly: an app embedding a wallet SDK that continuously POSTs
+ * telemetry to its vendor host never settles, so EVERY assertion on that app returns
+ * `unknown / outcome_pending` whatever the feature under test was. A third-party beacon cannot
+ * answer "has the app finished?", and nothing makes it stop, so waiting for it is waiting forever.
+ *
+ * Fails OPEN: with no known app origin nothing is foreign, because suppressing a request we cannot
+ * classify is how a verdict starts resting on evidence it discarded.
+ *
+ * SAME-ORIGIN background traffic is never guessed: nothing in a URL separates the app's telemetry
+ * from the app's work. It is excluded only when the project DECLARED it (`background`).
+ */
+const isForeign = (data, appOrigin, background) => isForeignTraffic('string' === typeof data['url'] ? data['url'] : undefined, appOrigin, background);
 /**
  * A departure records where the browser was SENT, not a request whose result we will see — the
  * response is delivered to a document this session does not live into. It can never be matched by a
@@ -54,7 +73,7 @@ const idOf = (data) => 'string' === typeof data['id'] ? data['id'] : undefined;
  * the act cursor, so a response belonging to an earlier action can land inside it, and counting that
  * as progress would let unrelated traffic close the window early.
  */
-export function inFlightRequestIds(events) {
+export function inFlightRequestIds(events, appOrigin, background = []) {
     const settled = new Set();
     for (const e of events) {
         if (e.type !== EventType.NET_REQUEST)
@@ -67,6 +86,8 @@ export function inFlightRequestIds(events) {
     for (const e of events) {
         if (e.type !== EventType.NET_PENDING || isDevTooling(e.data) || isDeparture(e.data))
             continue;
+        if (isForeign(e.data, appOrigin, background))
+            continue;
         const id = idOf(e.data);
         if (id !== undefined && !settled.has(id) && !open.includes(id))
             open.push(id);
@@ -81,8 +102,8 @@ export function inFlightRequestIds(events) {
  * directly. Read off the NET_PENDING the window already holds, so this costs one pass over events
  * that are in hand.
  */
-export function inFlightRequestLabels(events) {
-    const open = new Set(inFlightRequestIds(events));
+export function inFlightRequestLabels(events, appOrigin, background = []) {
+    const open = new Set(inFlightRequestIds(events, appOrigin, background));
     const labels = [];
     for (const e of events) {
         if (e.type !== EventType.NET_PENDING)
@@ -136,7 +157,9 @@ export function repeatedRequestLabels(events) {
  * timeout reaching the predicate, and a negative deadline must mean "stop", never "loop forever".
  */
 export async function waitForInFlight(session, since, budgetMs, opts) {
-    let open = inFlightRequestIds(session.eventsSince(since));
+    // The verdict's own scope: waiting on a request the verdict will not count is latency for nothing.
+    const outstanding = () => inFlightRequestIds(session.eventsSince(since), session.url, session.background);
+    let open = outstanding();
     if (0 === open.length)
         return { settled: true, stillInFlight: [] };
     if (budgetMs <= 0)
@@ -145,7 +168,7 @@ export async function waitForInFlight(session, since, budgetMs, opts) {
     while (session.elapsed() < deadline) {
         // Never overshoot the budget: the last sleep is trimmed to whatever is actually left.
         await opts.sleep(Math.min(POLL_MS, deadline - session.elapsed()));
-        open = inFlightRequestIds(session.eventsSince(since));
+        open = outstanding();
         if (0 === open.length)
             return { settled: true, stillInFlight: [] };
     }

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

@@ -10,7 +10,7 @@
  * must never fail the run that found it.
  */
 import { ActionType, AnchorKind } from '@reticlehq/core';
-import { CapsuleStore, capsuleId, CAPSULE_VERSION } from '../../judgement/capsule/capsule-store.js';
+import { CapsuleStore, capsuleFingerprint, capsuleId, CAPSULE_VERSION, } from '../../judgement/capsule/capsule-store.js';
 import { ReticleTool } from '@reticlehq/core';
 import { asRecord, asString } from '@reticlehq/core';
 import { sessionRoot } from '../../memory/project/session-root.js';
@@ -19,7 +19,6 @@ export async function saveFailedAssertCapsule(inputs) {
     const { deps, verdict, capsule, links, args, actResult, actedSource, root: given } = inputs;
     if (verdict.pass || capsule === undefined)
         return undefined;
-    const id = capsuleId(deps.now(), asString(args['ref']) ?? 'assert');
     const expectedText = links
         .map((l) => ('name' in l ? `${l.kind} ${String(l.name)}` : l.kind))
         .join(' AND ');
@@ -33,10 +32,20 @@ export async function saveFailedAssertCapsule(inputs) {
     // verdict is already built, and losing the capsule must never also lose the verdict.
     if (root === undefined)
         return undefined;
-    const saved = await new CapsuleStore(deps.fs, root).save({
+    // Built BEFORE the id, because the id carries the fingerprint of this body — that is what lets a
+    // retry of the same broken step fold into the capsule already on disk instead of adding a file.
+    /*
+     * What this capsule is ABOUT, for its filename and its anchor.
+     *
+     * The testid is the element said in a name a human chose; `args.ref` is a volatile handle minted
+     * per session, meaningless an hour later and anywhere else. The anchor may still fall back to the
+     * ref, because the anchor has to address the element and the ref is what addressed it. The NAME
+     * must not: a capsule is durable, meant to be committed, and read by somebody who was not there.
+     */
+    const testid = asString(asRecord(actResult.result)['testid']);
+    const action = asString(args['action']) ?? ActionType.CLICK;
+    const body = {
         version: CAPSULE_VERSION,
-        id,
-        createdAt: deps.now(),
         origin: 'failed-assert',
         expected: expectedText.length > 0 ? expectedText : 'declared consequence',
         observed: capsule.firstDivergence?.observed ?? verdict.failureReason ?? 'not observed',
@@ -45,14 +54,20 @@ export async function saveFailedAssertCapsule(inputs) {
                 tool: ReticleTool.ACT,
                 anchor: {
                     kind: AnchorKind.TESTID,
-                    value: asString(asRecord(actResult.result)['testid']) ?? asString(args['ref']) ?? '',
+                    value: testid ?? asString(args['ref']) ?? '',
                     // Carried so the saved capsule — which outlives this turn and becomes a regression flow
                     // when it goes green — still knows which file the failure came from.
                     ...(actedSource === undefined ? {} : { source: actedSource }),
                 },
-                action: (asString(args['action']) ?? ActionType.CLICK),
+                action: action,
             },
         ],
+    };
+    const id = capsuleId(deps.now(), testid ?? action, capsuleFingerprint(body));
+    const saved = await new CapsuleStore(deps.fs, root).save({
+        ...body,
+        id,
+        createdAt: deps.now(),
     });
     return saved ? id : undefined;
 }

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

@@ -42,7 +42,6 @@ import { waitForReaction } from './act/react-grace.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 +51,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 +64,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.
  *
@@ -428,22 +429,10 @@ 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;
             try {
                 // actCommand is the single interception point for upload+path rewrite.
                 //
@@ -472,8 +461,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,7 +470,7 @@ 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;
@@ -654,17 +643,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 stillInFlight = inFlightRequestLabels(windowEvents, session.url, session.background);
                 const decision = 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
@@ -770,6 +759,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 +776,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) }),
@@ -823,7 +824,7 @@ export const ACT_TOOLS = [
                     ...(0 === greenRadius.length ? {} : { blastRadius: greenRadius }),
                     since,
                     ...(session.id === actedSessionId ? {} : { sessionId: session.id }),
-                    ...healthEnvelope(session),
+                    ...healthEnvelope(currentOf(deps.sessions, session)),
                 });
             }
             finally {

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

@@ -115,11 +115,23 @@ export function gradeOfPredicate(predicate) {
             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 { 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?
@@ -147,9 +150,8 @@ changeUndeclared) {
         // treating that silence as an empty set would refuse every claim from every older page.
         channelsRead: channelsRead(predicate.kind),
         ...(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';
@@ -89,7 +89,8 @@ 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
@@ -103,7 +104,7 @@ 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, { navigatedId: session.id, priorIds }, timeoutMs)
                     : null;
                 return navigateResult(result, arrival, timeoutMs);
             }

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

@@ -25,6 +25,8 @@ function paramInfo(shape) {
 function unknownParamsError(toolName, unknown) {
     return `unknown ${1 === unknown.length ? 'parameter' : 'parameters'} for ${toolName}: ${unknown.join(', ')} — NOT applied, so any result would be an answer to a different question`;
 }
+/** The one `action` reticle_tools takes: every other tool on the surface is action-dispatched. */
+const TOOLS_LIST_ACTION = 'list';
 /** What to write instead — the one parameter reticle_tools declares, and the no-argument form. */
 const TOOLS_ARG_HINT = 'name the tools you want in `names`: reticle_tools { names: ["reticle_act_and_wait"] } — or call it with no arguments for the full catalog';
 /** The keys not declared by `shape`, in call order. */
@@ -92,6 +94,10 @@ callable) {
             },
         };
     const toolsShape = {
+        action: z
+            .literal(TOOLS_LIST_ACTION)
+            .optional()
+            .describe('"list": the catalogue, same as no arguments.'),
         names: z
             .array(z.string())
             .optional()

package/dist/surface/tools/feedback-tools.d.ts

@@ -8,7 +8,7 @@ export declare const FEEDBACK_TOOLS: ToolDef[];
  * Delivered ONCE per server process. A prompt on every verification would be nagging, and a nagged
  * user opts out of telemetry entirely, which costs us the counters too.
  */
-export declare const FEEDBACK_PROMPT: {
+declare const FEEDBACK_PROMPT: {
     readonly ask: "Ask the human, in your own words and only once: how did this verification go, and what would have made Reticle more useful? If they answer, file it with `reticle feedback` (they run it) or relay it yourself.";
     readonly command: "reticle feedback";
 };
@@ -33,3 +33,4 @@ export declare const VERDICT_TOOLS: ReadonlySet<string>;
  */
 export declare function takeFeedbackPrompt(toolName: string): typeof FEEDBACK_PROMPT | undefined;
 export declare function resetFeedbackPrompt(): void;
+export {};

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

@@ -196,7 +196,7 @@ export const FEEDBACK_TOOLS = [
  * Delivered ONCE per server process. A prompt on every verification would be nagging, and a nagged
  * user opts out of telemetry entirely, which costs us the counters too.
  */
-export const FEEDBACK_PROMPT = {
+const FEEDBACK_PROMPT = {
     ask: 'Ask the human, in your own words and only once: how did this verification go, and what would have made Reticle more useful? If they answer, file it with `reticle feedback` (they run it) or relay it yourself.',
     command: 'reticle feedback',
 };

package/dist/surface/tools/invoke-tool.js

@@ -17,7 +17,7 @@ import { reportOnboardingStep } from '../../telemetry/onboarding-funnel.js';
 import { noteActed, noteFirstVerdict, noteOnboardingFirst } from '../../telemetry/onboarding-firsts.js';
 import { withHarnessDrive } from '../../telemetry/harness-drive.js';
 import { OnboardingPhase, OnboardingStepStatus } from '@reticlehq/core/telemetry';
-import { asString } from '@reticlehq/core';
+import { DiscoveryInvite, asString } from '@reticlehq/core';
 import { SESSION_ID_ARG, sessionIdFromArgs, spentRefFromArgs } from './tools-helpers.js';
 import { EnvelopeKey } from './tool-kit.js';
 import { ReticleTool } from '@reticlehq/core';
@@ -134,7 +134,7 @@ export const SESSION_EXEMPT_TOOLS = new Set([
     // FLOW_HEAL is no longer a name runTool ever sees: it became `reticle_verify {action:"heal"}`,
     // and VERIFY is already listed here, so the exemption is inherited from the parent. Left as a
     // dangling name it would be a lie this file's own test 6 is written to catch.
-    ReticleTool.INTENT, // reads/writes .reticle/intent.json; sessionId only picks the project
+    ReticleTool.INTENT, // reads/writes .reticle/intent/; sessionId only picks the project
     ReticleTool.CONTEXT, // folds the journal + intent ledger; must still answer when nothing is connected
     ReticleTool.PROJECT, // reads .reticle/project.json
     // Reads the team's shared memory over HTTP; sessionId only resolves WHICH project's link file to
@@ -609,7 +609,13 @@ export async function runTool(tool, deps, args) {
         ? raw
         : {
             ...raw,
-            ...(friction !== undefined ? { [EnvelopeKey.FEEDBACK_INVITE]: inviteFor(friction) } : {}),
+            ...(friction !== undefined
+                ? {
+                    [EnvelopeKey.FEEDBACK_INVITE]: inviteFor(friction),
+                    // The moment Reticle got in somebody's way is the moment to offer them the founder.
+                    [EnvelopeKey.TALK_TO_US]: DiscoveryInvite.AGENT,
+                }
+                : {}),
             ...(prompt !== undefined ? { [EnvelopeKey.FEEDBACK_PROMPT]: prompt } : {}),
             ...(update !== undefined ? { [EnvelopeKey.UPDATE_AVAILABLE]: update } : {}),
             ...(skew !== undefined ? { [EnvelopeKey.VERSION_SKEW]: skew } : {}),
@@ -623,7 +629,14 @@ export async function runTool(tool, deps, args) {
         return result;
     // Reuse the session resolved above so the health envelope describes the SAME session the handler
     // drove; only re-resolve if the up-front attempt failed but the handler somehow succeeded.
-    const resolved = session ?? deps.sessions.resolve(rawSessionId);
+    const driven = session ?? deps.sessions.resolve(rawSessionId);
+    // ...unless the call replaced that document. A full navigation or reload registers a NEW Session
+    // under the same id (or under the id the result reports it arrived at), and the object resolved
+    // before the call is the page that unloaded: it reported itself hidden on the way out, so every
+    // response after a navigation said "throttled" about a tab that was fine. Describe what is there
+    // now. Optional-called because a test double is a partial SessionManager.
+    const arrivedId = 'string' === typeof result['sessionId'] ? result['sessionId'] : driven.id;
+    const resolved = deps.sessions.get?.(arrivedId) ?? driven;
     const envelope = {};
     // The health block is idempotent: add it only when the handler didn't already include a `session`.
     if (!('session' in result))

package/dist/surface/tools/lease-hint.d.ts

@@ -36,6 +36,14 @@ export interface LeaseEvidence {
      * reported as a marker that was not found.
      */
     sdkMarker?: boolean;
+    /**
+     * The page's own Content-Security-Policy, read off the served document, when it refuses the
+     * bridge. Proof rather than a guess: the connection cannot happen until the policy allows it.
+     */
+    cspBlock?: {
+        problem: string;
+        fix: string;
+    };
     /**
      * The websocket URL the leased page actually tried, read from its own console.
      *

package/dist/surface/tools/lease-hint.js

@@ -85,6 +85,16 @@ export function leaseNotConnectedHint(url, port, evidence = {}) {
             `RETICLE_PORT, or the build plugin's \`port\`), and \`VITE_RETICLE_WS_URL\` overrides it ` +
             `outright.${marker} ${RELEASE}`);
     }
+    // 0b. The page's own policy forbids the connection. Read off the document it served, so it is
+    //     proof about the page in hand, and it holds whether or not the app ships an SDK: neither
+    //     `init` nor the zero-install reader can dial out of a page that forbids it. Every cause
+    //     below presupposes a page that is allowed to connect, which is why this comes first.
+    if (evidence.cspBlock !== undefined) {
+        return (`${opening} This page's Content-Security-Policy blocks the connection: ` +
+            `${evidence.cspBlock.problem}. That is true whether or not the app has Reticle installed, ` +
+            `so installing it will not help until the policy allows the bridge. For development, ` +
+            `${evidence.cspBlock.fix}. ${RELEASE}`);
+    }
     // 1. A recorded refusal. The only cause with proof behind it, so nothing outranks it.
     if (evidence.refusal !== undefined) {
         return `${opening} A dial DID arrive and was refused: ${evidence.refusal}${marker} ${RELEASE}`;