@reticlehq/server 3.7.0 → 3.8.1

package/dist/surface/tools/read/query-shape.js

@@ -37,3 +37,18 @@ export function normalizeQueryArgs(args) {
     }
     return args;
 }
+/** How the refusal of an empty find opens: the error table recognizes it by these words. */
+export const EMPTY_FIND_OPENING = 'Nothing was searched: this find names nothing to find.';
+/**
+ * The error for a query that names nothing to find, or `undefined` when it names something.
+ *
+ * Sent to the page, an empty query answered `count: 0`, which reads as "nothing here matches" about
+ * a question nobody asked. A container asked for itself (`self`) needs no other field.
+ */
+export function emptyQueryRefusal(args) {
+    if (true === args['self'] || 'string' === typeof args['by'] || 'string' === typeof args['value'])
+        return undefined;
+    return new Error(`${EMPTY_FIND_OPENING} Pass one of testid, text, role ` +
+        '(with name), label, placeholder or alt, e.g. { testid: "submit" } or { role: "button", ' +
+        'name: "Save" }, or `by` with `value`.');
+}

package/dist/surface/tools/read/snapshot-unmounted-note.d.ts

@@ -0,0 +1 @@
+export declare function noteUnmountedRoot(result: unknown, mode: string, session?: unknown, scope?: string): unknown;

package/dist/surface/tools/read/snapshot-unmounted-note.js

@@ -0,0 +1,73 @@
+import { EventType, SnapshotMode, asNumber, asRecord, asString } from '@reticlehq/core';
+/**
+ * How much DOM there is under the mount container, when the tree is empty and nothing was skipped.
+ *
+ * A handful of elements is a container with nothing in it. React's own root div counts as one, and a
+ * wrapper or two is ordinary, so this is deliberately not `=== 0`.
+ */
+const UNMOUNTED_ROOT_MAX_ELEMENTS = 3;
+function crashEvidence(session) {
+    const since = asRecord(session)['eventsSince'];
+    if ('function' !== typeof since)
+        return undefined;
+    let events;
+    try {
+        events = since.call(session, 0);
+    }
+    catch {
+        return undefined;
+    }
+    if (!Array.isArray(events))
+        return undefined;
+    const errors = events.filter((e) => {
+        const type = asString(asRecord(e)['type']);
+        return EventType.CONSOLE_ERROR === type || EventType.ERROR_UNCAUGHT === type;
+    });
+    if (0 === errors.length)
+        return undefined;
+    const first = errors
+        .map((e) => asString(asRecord(asRecord(e)['data'])['message']))
+        .find((m) => undefined !== m && '' !== m);
+    return { count: errors.length, first: first ?? '' };
+}
+export function noteUnmountedRoot(result, mode, session, scope) {
+    // A scope narrows the walk to one element, so a near-empty DOM under it says nothing about the app.
+    if (SnapshotMode.STATUS === mode || (scope ?? '') !== '')
+        return result;
+    const row = asRecord(result);
+    if (0 !== asNumber(row['nodes']))
+        return result;
+    if (row['note'] !== undefined)
+        return result;
+    const elements = asNumber(row['domElements']);
+    if (elements === undefined || elements > UNMOUNTED_ROOT_MAX_ELEMENTS)
+        return result;
+    const mount = `the tree is empty because there is almost nothing in the DOM: ${String(elements)} ` +
+        `element(s) under this scope. That is a mount container with nothing rendered into it, not a ` +
+        `page whose contents were skipped — so the app is UNMOUNTED rather than slow, and waiting ` +
+        `will not change it. `;
+    // An uncaught error beside an empty mount container is the difference between "has not started"
+    // and "started and died", which are the two readings of this count and want opposite next moves.
+    // Nothing here is framework-specific, and deliberately so: the condition is a known mount
+    // container that holds nothing with an uncaught error beside it, which is as true of a Vue or
+    // Svelte root as a React one.
+    const crash = crashEvidence(session);
+    if (crash !== undefined) {
+        return {
+            ...row,
+            note: mount +
+                `The app did not merely fail to start — it CRASHED: ${String(crash.count)} uncaught ` +
+                `error(s) were logged in this session` +
+                ('' === crash.first ? '' : `, the first: "${crash.first}"`) +
+                `. Read reticle_console for the rest, and check anything that runs inside a framework ` +
+                `commit phase. Loading the app again will reproduce it rather than fix it.`,
+        };
+    }
+    return {
+        ...row,
+        note: mount +
+            `An app that was rendering and then stopped has usually thrown: read ` +
+            `reticle_console for an uncaught error, and check anything that runs inside a framework ` +
+            `commit phase. If the app has genuinely not started yet, load it and snapshot again.`,
+    };
+}

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

@@ -199,7 +199,7 @@ export const READ_TOOLS = [
         },
         outputSchema: {
             recordingName: z.string(),
-            program: z.unknown(),
+            program: z.unknown().optional(),
             warning: z.string().optional(),
             proposedConsequences: z
                 .array(z.unknown())
@@ -386,7 +386,7 @@ export const READ_TOOLS = [
             ...sessionIdShape,
         },
         outputSchema: {
-            stores: z.record(z.unknown()).optional(),
+            stores: z.record(z.string(), z.unknown()).optional(),
             storeNames: z.array(z.string()).optional(),
             found: z.boolean().optional(),
             value: z.unknown().optional(),
@@ -598,9 +598,9 @@ export const READ_TOOLS = [
             ...sessionIdShape,
         },
         outputSchema: {
-            local: z.record(z.string()).optional(),
-            session: z.record(z.string()).optional(),
-            cookies: z.record(z.string()).optional(),
+            local: z.record(z.string(), z.string()).optional(),
+            session: z.record(z.string(), z.string()).optional(),
+            cookies: z.record(z.string(), z.string()).optional(),
             area: z.string().optional(),
             key: z.string().optional(),
             value: z.string().optional(),

package/dist/surface/tools/real-input-attempt.d.ts

@@ -49,6 +49,8 @@ interface RealActResult {
  * rather than pretend the action ran.
  */
 export declare const HOVER_NEEDS_POINTER_MSG = "cannot hover without a real pointer \u2014 CSS :hover only applies to a native mouse move, never to a synthetic mouseover";
+/** A hover target the page could not bring into the viewport. The pointer would miss it. */
+export declare const HOVER_OFF_VIEWPORT_MSG = "cannot hover: the target is outside the viewport and could not be scrolled into view, so a real pointer would miss it";
 /**
  * Attempt to drive a pointer action via native input. Returns a synthetic outcome (with a
  * `reason` when a provider is configured) whenever the synthetic path should run — no matching
@@ -60,4 +62,13 @@ export declare const HOVER_NEEDS_POINTER_MSG = "cannot hover without a real poin
  * or throws.
  */
 export declare function tryRealInput(deps: ToolDeps, session: Session, ref: string, action: ActionType, args: Record<string, unknown>): Promise<RealActResult>;
+/**
+ * The session a flow replay runs on, with a press sent to the lease's real keyboard.
+ *
+ * Replay dispatches its steps itself, not through `reticle_act`, so a recorded Tab replayed as a
+ * synthetic keydown that moves no focus, and a keyboard flow that passed live drifted on replay.
+ * Every other command, and a press this lease cannot drive for real, goes to the page as before.
+ * A Proxy, not a copy: the session keeps private state its own methods read.
+ */
+export declare function withLeaseKeyboard(deps: ToolDeps, session: Session): Session;
 export {};

package/dist/surface/tools/real-input-attempt.js

@@ -19,9 +19,10 @@
  * the base64 4/3 inflation factor applied, so the encoded payload always fits in one WebSocket
  * frame.
  */
-import { ActionType, DriveErrorCode, InputModeReason, ReticleCommand, TRANSPORT_LIMITS, } from '@reticlehq/core';
+import { ActionType, DriveErrorCode, ElementState, INSPECT_IN_VIEWPORT_FIELD, INSPECT_REVEAL_ARG, InputMode, InputModeReason, ReticleCommand, TRANSPORT_LIMITS, } from '@reticlehq/core';
 import { boxCenter, DriveError, isRealInputAction, unspellablePressReason, } from '../../portal/input/real-input.js';
 import { assertDragNotDestructive, assertNotDestructive } from './act/act-danger.js';
+import { assertNativeAllowed } from '../../portal/production/production-drive.js';
 import { NATIVE_INPUT_ARG } from '@reticlehq/core';
 import { asNumber, asRecord, asString } from '@reticlehq/core';
 import { commandOrThrow } from './tool-kit.js';
@@ -162,7 +163,10 @@ async function resolveUploadPath(rawPath, projectRoot, fs, uploadRoots, home) {
     const real = await fs.realpath(abs).catch(() => {
         throw new Error(`upload path '${rawPath}' could not be read: file not found or not accessible.`);
     });
-    const allowed = [projectRoot, ...uploadRoots];
+    // The roots go through realpath too, or one path compares under two spellings: a Windows 8.3
+    // short name (`RUNNER~1`) against the long name realpath returns, or macOS `/tmp` against
+    // `/private/tmp`. A root that cannot be resolved keeps the spelling it was given.
+    const allowed = await Promise.all([projectRoot, ...uploadRoots].map((root) => fs.realpath(root).catch(() => root)));
     if (!allowed.some((root) => isInsideRoot(real, root))) {
         const listed = allowed.map((r) => `'${r}'`).join(', ');
         throw new Error(`upload path '${rawPath}' resolves to '${real}', which is outside every allowed upload root ` +
@@ -228,6 +232,94 @@ function synthetic(reason) {
         ? { result: undefined, settled: false }
         : { result: undefined, settled: false, reason };
 }
+/** The act's args, as the real-input driver reads them. */
+function performArgsOf(inner) {
+    const performArgs = {};
+    const value = asString(inner['value']);
+    if (value !== undefined)
+        performArgs.value = value;
+    const text = asString(inner['text']);
+    if (text !== undefined)
+        performArgs.text = text;
+    const key = asString(inner['key']);
+    if (key !== undefined)
+        performArgs.key = key;
+    const modifiers = inner['modifiers'];
+    if (Array.isArray(modifiers)) {
+        performArgs.modifiers = modifiers.filter((m) => 'string' === typeof m);
+    }
+    // A held key is the whole point of a hold-to-confirm control, and the synthetic path has honoured
+    // `holdMs` all along. Not forwarding it made the real keyboard the WEAKER of the two paths: it
+    // drove the key instantly and reported a hold that never held.
+    const holdMs = asNumber(inner['holdMs']);
+    if (holdMs !== undefined)
+        performArgs.holdMs = holdMs;
+    // `keys` and `code` are read but not forwarded: both are routed away by the caller — a multi-key
+    // sequence and an explicit physical code have no driver spelling — so carrying them into the
+    // provider would only invite it to guess at a gesture the caller did not ask for.
+    return performArgs;
+}
+/** The fields an act result names its element by, which the flow recorder anchors a step on. */
+const ANCHOR_FIELDS = [
+    'testid',
+    'testidOf',
+    'component',
+    'source',
+    'role',
+    'name',
+    'nth',
+    'of',
+    'secret',
+];
+/**
+ * Press with a leased page's real keyboard, or undefined when this session is not such a lease.
+ *
+ * A lease is Reticle's own Playwright page, so it has a real keyboard with no `reticle drive`
+ * provider configured. Without this, Tab moved no focus and Enter or Space on a focused button did
+ * nothing, so a keyboard-only journey could be audited and never driven.
+ *
+ * A press that names an element focuses it first, inside the caller's `beginAction` window, the
+ * way a person tabs to a control and then presses the key. An element that does not take focus
+ * keeps the in-page press, with the reason: a person's keyboard could not reach it either.
+ * ponytail: lease only; the drive provider keeps its documented element-press rule.
+ */
+async function pressOnLease(deps, session, ref, inner) {
+    const pool = deps.pool;
+    if (pool === undefined || !pool.hasKeyboard(session.id))
+        return undefined;
+    const unspellable = unspellablePressReason('', inner);
+    if (unspellable !== undefined)
+        return synthetic(unspellable);
+    // What the focused element is called, from the focus act's own report, so the saved step can
+    // find it again: the real keyboard reports no element of its own.
+    let anchor = {};
+    if (0 < ref.length) {
+        const focus = asRecord(await commandOrThrow(deps, session.id, ReticleCommand.ACT, {
+            ref,
+            action: ActionType.FOCUS,
+            args: {},
+        }));
+        anchor = Object.fromEntries(ANCHOR_FIELDS.flatMap((k) => (k in focus ? [[k, focus[k]]] : [])));
+        const inspected = asRecord(await commandOrThrow(deps, session.id, ReticleCommand.INSPECT, { ref }));
+        const states = Array.isArray(inspected['states']) ? inspected['states'] : [];
+        if (!states.includes(ElementState.FOCUSED)) {
+            return synthetic(InputModeReason.TARGET_NOT_FOCUSABLE);
+        }
+    }
+    const performed = await pool.pressLease(session.id, performArgsOf(inner));
+    if (performed?.performed !== true)
+        return undefined;
+    return {
+        result: {
+            ...anchor,
+            performed: true,
+            action: ActionType.PRESS,
+            inputMode: InputMode.REAL,
+            ...(performed.heldMs !== undefined ? { heldMs: performed.heldMs } : {}),
+        },
+        settled: true,
+    };
+}
 /**
  * Filler for the provider signature, which demands a box on every action.
  *
@@ -241,8 +333,36 @@ const PRESS_HAS_NO_BOX = { x: 0, y: 0, width: 0, height: 0 };
  * rather than pretend the action ran.
  */
 export const HOVER_NEEDS_POINTER_MSG = 'cannot hover without a real pointer — CSS :hover only applies to a native mouse move, never to a synthetic mouseover';
-function hoverSucceeded(center) {
-    return { result: { performed: true, center, action: ActionType.HOVER }, settled: true };
+/** A hover target the page could not bring into the viewport. The pointer would miss it. */
+export const HOVER_OFF_VIEWPORT_MSG = 'cannot hover: the target is outside the viewport and could not be scrolled into view, so a real pointer would miss it';
+/**
+ * INSPECT a ref for a real gesture, asking the page to scroll it into view first (#1711).
+ *
+ * A real gesture aims at coordinates. An element above or below the viewport has a box off the page,
+ * so the pointer lands on nothing while the provider reports `performed: true`. The synthetic path
+ * scrolls the target in first; this gives the real path the same step in the same round trip.
+ */
+async function inspectRevealed(deps, session, ref) {
+    const inspected = await commandOrThrow(deps, session.id, ReticleCommand.INSPECT, {
+        ref,
+        [INSPECT_REVEAL_ARG]: true,
+    });
+    const record = asRecord(inspected);
+    // Read the page's own measurement, taken after the scroll. `states` is no substitute: INSPECT
+    // builds it with `describe()`, which never adds `inViewport`, so every element read as out.
+    const inView = false !== record[INSPECT_IN_VIEWPORT_FIELD];
+    return { inspected, inView, scrolled: true === record['scrolledIntoView'] };
+}
+function hoverSucceeded(center, scrolled) {
+    return {
+        result: {
+            performed: true,
+            center,
+            action: ActionType.HOVER,
+            ...(scrolled ? { scrolledIntoView: true } : {}),
+        },
+        settled: true,
+    };
 }
 /**
  * Drive hover through a real pointer (CDP provider, then a leased Playwright page), or refuse.
@@ -256,19 +376,21 @@ async function hoverForReal(deps, session, ref, inner, provider) {
     if (!providerReady && deps.pool === undefined) {
         throw new Error(HOVER_NEEDS_POINTER_MSG);
     }
-    const inspected = await commandOrThrow(deps, session.id, ReticleCommand.INSPECT, { ref });
+    const { inspected, inView, scrolled } = await inspectRevealed(deps, session, ref);
     assertNotDestructive(ActionType.HOVER, inner, inspected);
     const box = asBox(inspected);
     if (box === undefined) {
         throw new Error(HOVER_NEEDS_POINTER_MSG);
     }
+    if (!inView)
+        throw new Error(HOVER_OFF_VIEWPORT_MSG);
     if (providerReady && provider !== undefined) {
         try {
             const performed = await provider.perform(session.url, ActionType.HOVER, box, {});
             // Hover always has a resolved box, so there is always a center to report: the provider's own
             // reading, or the box's if it reported none. Both are the same point, not a fabricated one.
             if (performed.performed)
-                return hoverSucceeded(performed.center ?? boxCenter(box));
+                return hoverSucceeded(performed.center ?? boxCenter(box), scrolled);
         }
         catch {
             // A provider error used to fall back to synthetic dispatch. For hover that is a lie.
@@ -276,7 +398,7 @@ async function hoverForReal(deps, session, ref, inner, provider) {
     }
     const { cx, cy } = boxCenter(box);
     if (true === (await deps.pool?.hoverLease(session.id, cx, cy))) {
-        return hoverSucceeded({ cx, cy });
+        return hoverSucceeded({ cx, cy }, scrolled);
     }
     throw new Error(HOVER_NEEDS_POINTER_MSG);
 }
@@ -297,7 +419,18 @@ export async function tryRealInput(deps, session, ref, action, args) {
     if (action === ActionType.HOVER) {
         return hoverForReal(deps, session, ref, inner, provider);
     }
+    // The production policy judges a command by the control it names, when the daemon dispatches
+    // it. A native key goes to whatever holds focus, so the policy cannot see what it presses. On a
+    // production drive a press runs in the page, where the daemon judges it.
+    if (action === ActionType.PRESS && session.production !== undefined) {
+        return synthetic(InputModeReason.PRODUCTION_PRESS_IN_PAGE);
+    }
     if (provider === undefined) {
+        if (action === ActionType.PRESS) {
+            const leased = await pressOnLease(deps, session, ref, inner);
+            if (leased !== undefined)
+                return leased;
+        }
         // Silent by default: with no provider EVERY action is synthetic, and a reason on all of them is
         // noise on the most-used tool in the product. But an agent that passed native:true asked a
         // question and got the opposite answer — reported from the field as a silent downgrade that cost
@@ -335,29 +468,7 @@ export async function tryRealInput(deps, session, ref, action, args) {
     }
     if (!(await provider.isAvailableFor(session.url)))
         return synthetic(InputModeReason.PAGE_NOT_CORRELATED);
-    const performArgs = {};
-    const value = asString(inner['value']);
-    if (value !== undefined)
-        performArgs.value = value;
-    const text = asString(inner['text']);
-    if (text !== undefined)
-        performArgs.text = text;
-    const key = asString(inner['key']);
-    if (key !== undefined)
-        performArgs.key = key;
-    const modifiers = inner['modifiers'];
-    if (Array.isArray(modifiers)) {
-        performArgs.modifiers = modifiers.filter((m) => 'string' === typeof m);
-    }
-    // A held key is the whole point of a hold-to-confirm control, and the synthetic path has honoured
-    // `holdMs` all along. Not forwarding it made the real keyboard the WEAKER of the two paths: it
-    // drove the key instantly and reported a hold that never held.
-    const holdMs = asNumber(inner['holdMs']);
-    if (holdMs !== undefined)
-        performArgs.holdMs = holdMs;
-    // `keys` and `code` are read but not forwarded: both are routed away above — a multi-key sequence
-    // and an explicit physical code have no driver spelling — so carrying them into the provider would
-    // only invite it to guess at a gesture the caller did not ask for.
+    const performArgs = performArgsOf(inner);
     // A document key has no element of its own: skip INSPECT and the box entirely.
     if (action === ActionType.PRESS) {
         try {
@@ -402,25 +513,41 @@ export async function tryRealInput(deps, session, ref, action, args) {
             };
         }
     }
-    const inspected = await commandOrThrow(deps, session.id, ReticleCommand.INSPECT, { ref });
+    const source = await inspectRevealed(deps, session, ref);
+    const { inspected } = source;
+    let { scrolled } = source;
     assertNotDestructive(action, inner, inspected);
-    const box = asBox(inspected);
-    if (box === undefined)
+    await assertNativeAllowed(session.production, action, inspected);
+    let box = asBox(inspected);
+    // A box outside the viewport after the reveal is a gesture that would land on nothing. The
+    // synthetic path scrolls and hit-tests on its own, so it is the honest answer.
+    if (box === undefined || !source.inView)
         return synthetic(InputModeReason.ELEMENT_NOT_LOCATABLE);
     let toBox;
     if (action === ActionType.DRAG) {
         const toRef = asString(inner['toRef']);
         if (toRef === undefined)
             return synthetic(InputModeReason.DRAG_TARGET_UNRESOLVED);
-        const targetInspected = await commandOrThrow(deps, session.id, ReticleCommand.INSPECT, {
-            ref: toRef,
-        });
+        const target = await inspectRevealed(deps, session, toRef);
+        const targetInspected = target.inspected;
         // A drag is judged on BOTH ends: dropping onto "Trash" is destructive however innocent the
         // thing being dragged looks.
         assertDragNotDestructive(inner, inspected, targetInspected);
         toBox = asBox(targetInspected);
-        if (toBox === undefined)
+        if (toBox === undefined || !target.inView) {
             return synthetic(InputModeReason.DRAG_TARGET_UNRESOLVED);
+        }
+        // Scrolling the drop target in can carry the source out, so read the source again. Only when
+        // the page moved. If the page has to scroll AGAIN to show the source, the two ends do not fit on
+        // one screen, and a real drag between them cannot land.
+        if (target.scrolled) {
+            scrolled = true;
+            const again = await inspectRevealed(deps, session, ref);
+            box = asBox(again.inspected);
+            if (box === undefined || !again.inView || again.scrolled) {
+                return synthetic(InputModeReason.ELEMENT_NOT_LOCATABLE);
+            }
+        }
     }
     if (toBox !== undefined)
         performArgs.toBox = toBox;
@@ -428,7 +555,15 @@ export async function tryRealInput(deps, session, ref, action, args) {
         const performed = await provider.perform(session.url, action, box, performArgs);
         if (!performed.performed)
             return synthetic(InputModeReason.PROVIDER_DECLINED);
-        return { result: { performed: true, center: performed.center, action }, settled: true };
+        return {
+            result: {
+                performed: true,
+                center: performed.center,
+                action,
+                ...(scrolled ? { scrolledIntoView: true } : {}),
+            },
+            settled: true,
+        };
     }
     catch {
         if (session.versionSkew !== undefined)
@@ -441,3 +576,36 @@ export async function tryRealInput(deps, session, ref, action, args) {
         };
     }
 }
+/**
+ * The session a flow replay runs on, with a press sent to the lease's real keyboard.
+ *
+ * Replay dispatches its steps itself, not through `reticle_act`, so a recorded Tab replayed as a
+ * synthetic keydown that moves no focus, and a keyboard flow that passed live drifted on replay.
+ * Every other command, and a press this lease cannot drive for real, goes to the page as before.
+ * A Proxy, not a copy: the session keeps private state its own methods read.
+ */
+export function withLeaseKeyboard(deps, session) {
+    if (deps.realInput !== undefined || deps.pool?.hasKeyboard(session.id) !== true)
+        return session;
+    const command = async (name, args = {}, timeoutMs) => {
+        if (ReticleCommand.ACT === name && ActionType.PRESS === args['action']) {
+            const ref = asString(args['ref']) ?? '';
+            const real = await tryRealInput(deps, session, ref, ActionType.PRESS, args);
+            if (real.result !== undefined) {
+                const result = { dispatched: true, settled: real.settled, ...asRecord(real.result) };
+                return { kind: 'command_result', id: ActionType.PRESS, ok: true, result };
+            }
+        }
+        return session.command(name, args, timeoutMs);
+    };
+    return new Proxy(session, {
+        get(target, key) {
+            if ('command' === key)
+                return command;
+            const value = Reflect.get(target, key, target);
+            return 'function' === typeof value
+                ? value.bind(target)
+                : value;
+        },
+    });
+}

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

@@ -1,4 +1,5 @@
 import { bodyCaptureRemedy } from '@reticlehq/engine/evidence/body-capture-remedy.js';
+import { sharedSkipReason } from '@reticlehq/engine/question/predicate/predicate-eval.js';
 import { z } from 'zod';
 import { witnessDisagreement, WitnessOutcome, } from '@reticlehq/engine/disagreement/witness-disagreement.js';
 /** How long to wait on the outside observer. Short: it is a read model, not the app under test. */
@@ -32,6 +33,7 @@ async function capturedBodies(session, since, urlContains) {
     let withBody = 0;
     let total = 0;
     let truncated = 0;
+    const skipReasons = [];
     for (const event of events) {
         if (event.type !== EventType.NET_REQUEST)
             continue;
@@ -40,8 +42,10 @@ async function capturedBodies(session, since, urlContains) {
             continue;
         total += 1;
         const raw = event.data['responseBody'];
-        if (typeof raw !== 'string' || 0 === raw.length)
+        if (typeof raw !== 'string' || 0 === raw.length) {
+            skipReasons.push(event.data['responseBodyReason']);
             continue;
+        }
         // A capped body is not an absent one. Recover the records that closed before the cut rather than
         // reporting nothing about the page with the most data on it.
         const salvaged = salvageJson(raw);
@@ -52,7 +56,7 @@ async function capturedBodies(session, since, urlContains) {
         if (salvaged.partial)
             truncated += 1;
     }
-    return { bodies, withBody, total, truncated };
+    return { bodies, withBody, total, truncated, skipReasons };
 }
 export const RECONCILE_TOOLS = [
     {
@@ -68,6 +72,10 @@ export const RECONCILE_TOOLS = [
                 .string()
                 .optional()
                 .describe('Only compare responses from URLs containing this, e.g. "/api/v1/settlements".'),
+            scope: z
+                .string()
+                .optional()
+                .describe('A ref or CSS selector, e.g. "#status". Compare only against that subtree. Use it when the whole page is too large to read completely (a card of large native selects) and the API feeds one region. A scope that matches no element is refused, not read as an empty page.'),
             witness: z
                 .object({
                 url: z.string().url(),
@@ -93,7 +101,7 @@ export const RECONCILE_TOOLS = [
         handler: async (deps, args) => {
             const session = deps.sessions.resolve(asString(args['sessionId']));
             const since = asNumber(args['since']) ?? 0;
-            const { bodies, withBody, total, truncated } = await capturedBodies(session, since, asString(args['urlContains']));
+            const { bodies, withBody, total, truncated, skipReasons } = await capturedBodies(session, since, asString(args['urlContains']));
             // An empty result over data that was never read is the exact false green this tool exists to
             // prevent, so the two cases are reported differently and neither is silent.
             if (0 === bodies.length) {
@@ -102,16 +110,19 @@ export const RECONCILE_TOOLS = [
                     compared: 0,
                     note: 0 === total
                         ? 'no responses in this window matched — nothing was compared'
-                        : `${String(total)} response(s) matched but NONE carried a recorded body, so nothing was compared. ${bodyCaptureRemedy(session.sdkVersion)}`,
+                        : `${String(total)} response(s) matched but NONE carried a recorded body, so nothing was compared. ${bodyCaptureRemedy(session.sdkVersion, sharedSkipReason(skipReasons))}`,
                 });
             }
             // The whole page, INCLUDING whatever the snapshot's node cap cut off. A comparison against a
             // prefix of the page can miss the row that disagrees and can invent one that does not — the
             // value it was looking for may simply sit past the cut.
+            // A caller-given `scope` narrows the read to one subtree (reticle#1545); every cut branch under
+            // it is still finished, so a clean result is a claim about that whole subtree.
+            const scopeArg = asString(args['scope']);
             const page = await readCompleteTree((scope) => commandOrThrow(deps, session.id, ReticleCommand.SNAPSHOT, {
                 mode: SnapshotMode.FULL,
                 ...(scope === undefined ? {} : { scope, includeRoot: true }),
-            }));
+            }), scopeArg);
             const mismatches = reconcile(bodies, page.tree);
             /*
              * Consult the observer outside the app, when one was named.
@@ -185,8 +196,9 @@ export const RECONCILE_TOOLS = [
             if (0 === mismatches.length && !page.complete && witness?.kind !== WitnessOutcome.DISAGREES) {
                 throw new Error(`the page could not be read completely — ${page.incompleteBecause ?? 'the snapshot was cut'}. ` +
                     'Nothing was found to disagree with the API, but that is not the same as nothing disagreeing: ' +
-                    'the record that does could be in the part that was never read. Narrow the page (close overlays, ' +
-                    'navigate to the view holding these records) and re-run.');
+                    'the record that does could be in the part that was never read. Narrow the read: pass `scope` ' +
+                    '(a ref or CSS selector for the region the API feeds), close overlays, or navigate to the view ' +
+                    'holding these records, then re-run.');
             }
             // A truncated body is declared whether or not anything was found in it: "no mismatches" over a
             // partially-read payload is a weaker statement than over a whole one, and the difference is
@@ -197,7 +209,8 @@ export const RECONCILE_TOOLS = [
                 }
                 : 0 === mismatches.length
                     ? {
-                        note: `compared ${String(withBody)} response(s); nothing on screen contradicts them`,
+                        note: `compared ${String(withBody)} response(s); nothing on screen contradicts them` +
+                            (scopeArg === undefined ? '' : ` inside \`${scopeArg}\``),
                     }
                     : {};
             return withControl(session, {

package/dist/surface/tools/reticle-result.d.ts

@@ -26,6 +26,7 @@ export interface ResultFacts {
     /** From `platformLine`. */
     platform: string;
 }
+export declare const seconds: (ms: number) => string;
 /**
  * Each fact once. The headline carries the check count, so the metrics do not repeat it; with one
  * check the headline is the whole tally, so the per-word count line is left out.
@@ -40,6 +41,8 @@ export declare function retitleResult(block: string, verified: Verified, because
 export declare const KEY_REFUSED_HEAD = "Not on the platform: ";
 /** The line for a key refused for no reason the platform named. */
 export declare const KEY_REFUSED_LINE: string;
+/** Linked to the platform: a dashboard, a link file or a key, refused or not. */
+export declare function linkedToPlatform(root: string, env: Record<string, string | undefined>): boolean;
 /** The platform line: where the run lives when linked, what linking adds when not. One line. */
 export declare function platformLine(root: string, env: Record<string, string | undefined>, runId?: string): string;
 /**

package/dist/surface/tools/reticle-result.js

@@ -47,7 +47,7 @@ const Said = {
     PITCH: 'Kept on this machine only. The Reticle platform adds run history, your team and Reticle Harness',
 };
 const plural = (n, word) => `${String(n)} ${word}${1 === n ? '' : 's'}`;
-const seconds = (ms) => ms < 60_000
+export const seconds = (ms) => ms < 60_000
     ? `${(ms / 1000).toFixed(1)}s`
     : `${String(Math.floor(ms / 60_000))}m ${String(Math.round((ms % 60_000) / 1000))}s`;
 function headline(f) {
@@ -126,6 +126,13 @@ export const KEY_REFUSED_HEAD = 'Not on the platform: ';
 const keyRefusedLine = (why) => `${KEY_REFUSED_HEAD}${why.replace(/\.$/, '')}. Mint a new key in Settings → API keys; the run is kept on this machine`;
 /** The line for a key refused for no reason the platform named. */
 export const KEY_REFUSED_LINE = keyRefusedLine(KEY_REFUSED);
+/** Linked to the platform: a dashboard, a link file or a key, refused or not. */
+export function linkedToPlatform(root, env) {
+    return (keyRefusalAtLastSync(root) !== undefined ||
+        readDashboardUrl(root) !== undefined ||
+        existsSync(join(root, ReticleDir.CLOUD_LINK_FILE)) ||
+        apiKeyFrom(env) !== undefined);
+}
 /** The platform line: where the run lives when linked, what linking adds when not. One line. */
 export function platformLine(root, env, runId) {
     // Before any link: a run the platform will refuse is not "saved" and not "on the dashboard".

package/dist/surface/tools/run-report.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The end-of-run report: the run ledger as the agent shows it to the user.
+ *
+ * Added to the answer of the call that ends an agent's run: a session end, a yield, or a released
+ * tab. A run that ended by releasing its tab got no word about the run before this, and its agent
+ * wrote its own summary. The report is a schema'd object, the markdown built from it, and one
+ * instruction. The cloud line is said only when the project is not linked, and it says what it is.
+ */
+import { RUN_REPORT_FIELD, type RunReport } from '@reticlehq/core';
+import type { RunLedger } from '../../judgement/runs/run-ledger.js';
+/** The report as markdown: the verdict, each claim with its evidence, then what the run left. */
+export declare function renderRunReport(report: RunReport): string;
+/** The calls that end an agent's run, by their own name or as an action of a merged tool. */
+export declare function endsRun(tool: string, args: Record<string, unknown>): boolean;
+/** What an answer says the run saved or read. An answer that refused counts for nothing. */
+export declare function noteToolResult(ledger: RunLedger, tool: string, args: Record<string, unknown>, result: unknown): void;
+/** The report as an answer field, or no field when the ledger holds no run. Empties the ledger. */
+export declare function runReportField(ledger: RunLedger, root: string | undefined, env: Record<string, string | undefined>, now: number): Partial<Record<typeof RUN_REPORT_FIELD, {
+    report: RunReport;
+    markdown: string;
+    instruction: string;
+}>>;