@reticlehq/server 2.3.0 → 2.5.0

package/dist/tools/act-tools.js

@@ -1,104 +1,34 @@
 /**
- * Action tools — reticle_act, reticle_act_sequence, reticle_act_and_wait — plus the native-input machinery
- * (asBox / tryRealInput). Split out of tools.ts to keep that file under the line cap; assembled back
- * into the tool list there via...ACT_TOOLS.
+ * Action tools — reticle_act, reticle_act_sequence, reticle_act_and_wait. Split out of tools.ts to keep
+ * that file under the line cap and assembled back into the tool list there via ...ACT_TOOLS; the
+ * native-input attempt itself lives in real-input-attempt.ts for the same reason.
  */
 import { z } from 'zod';
-import { compileActStep, compileSequenceStep } from '../flows/replay.js';
-import { ActionType, ActionWarning, DEFAULT_ASSERT_TIMEOUT_MS, InputMode, InputModeReason, ReticleCommand, } from '@reticlehq/core';
-import { isPointerAction } from '../input/real-input.js';
+import { aliasParam } from './alias-args.js';
+import { captureAct, compileSequenceStep } from '../flows/replay.js';
+import { ActionType, ActionWarning, DEFAULT_ASSERT_TIMEOUT_MS, InputMode, ReticleCommand, Verified, PredicateKind, } from '@reticlehq/core';
+import { assertNativeInputSupported } from './act-danger.js';
 import { leanActResult, mutatedWithin } from './act-view.js';
 import { ReticleTool } from './tool-names.js';
 import { buildReactionReport, summarizeReaction } from '../events/reaction.js';
 import { causalSummary } from '../capsule/causal-summary.js';
 import { findContradictions } from '../events/contradictions.js';
 import { decideVerified } from '../honesty/verified.js';
+import { readsDomState } from '../honesty/already-true.js';
 import { saveFailedAssertCapsule } from './act-capsule.js';
 import { buildDivergenceCapsule } from '../capsule/capsule.js';
 import { predicateToExpectedLinks } from '../capsule/predicate-to-links.js';
 import { buildHonestyBlock } from '../honesty/honesty.js';
-import { buildCoverageStatement, blindSpotsFromState, impeachesCapture, } from '../honesty/blind-spots.js';
+import { buildCoverageStatement, blindSpotsFromState, Coverage, impeachesCapture, } from '../honesty/blind-spots.js';
 import { hasAcceptedWrite } from '../honesty/accepted-write.js';
 import { hasUnreadWriteOutcome } from '../honesty/unread-outcome.js';
-import { assertDragNotDestructive, assertNotDestructive } from './act-danger.js';
 import { evaluatePredicate, waitForPredicate, provenExpectedLinks, PredicateSchema, } from '../events/predicate.js';
 import { healthEnvelope, refuseIfThrottled } from '../session/session-health.js';
-import { pausedShortCircuit, pausedOutputShape, withControl } from '../session/control-envelope.js';
+import { pausedShortCircuit, pausedOutputShape, withControl, PAUSED_NO_VERDICT, } from '../session/control-envelope.js';
 import { asString, asNumber, asRecord, sourceOf } from './tools-helpers.js';
-import { sessionIdShape, commandOrThrow } from './tool-kit.js';
-import { asActionType, asBox, gradeOf } from './act-helpers.js';
-/** Synthetic outcome with a diagnostic reason (provider configured but native input skipped). */
-function synthetic(reason) {
-    return reason === undefined
-        ? { result: undefined, settled: false }
-        : { result: undefined, settled: false, reason };
-}
-/**
- * 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
- * page, unresolvable box, declined, etc. A throw inside the provider becomes a synthetic fallback
- * flagged with `fellBack`. `result` is defined only on a real success.
- */
-async function tryRealInput(deps, session, ref, action, args) {
-    const provider = deps.realInput;
-    if (provider === undefined)
-        return synthetic(); // real input not configured — no diagnostic
-    if (!isPointerAction(action))
-        return synthetic(InputModeReason.NOT_POINTER); // fill/type stay synthetic
-    const inner = asRecord(args['args']);
-    // "Don't click, run the code": a click/dblclick runs the occlusion-honest SYNTHETIC path by default
-    // even with a provider configured — no coordinate gesture to be intercepted by the HUD or missed
-    // off-screen. Opt into a trusted native click with args.native:true (file pickers, clipboard,
-    // isTrusted-gated handlers). hover/drag genuinely need native pointer state, so they stay real.
-    if ((action === ActionType.CLICK || action === ActionType.DBLCLICK) && inner['native'] !== true) {
-        return synthetic(InputModeReason.SYNTHETIC_CLICK_PREFERRED);
-    }
-    if (!(await provider.isAvailableFor(session.url)))
-        return synthetic(InputModeReason.PAGE_NOT_CORRELATED);
-    const inspected = await commandOrThrow(deps, session.id, ReticleCommand.INSPECT, { ref });
-    assertNotDestructive(action, inner, inspected);
-    const box = asBox(inspected);
-    if (box === undefined)
-        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,
-        });
-        // 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)
-            return synthetic(InputModeReason.DRAG_TARGET_UNRESOLVED);
-    }
-    const performArgs = {};
-    const value = asString(inner['value']);
-    if (value !== undefined)
-        performArgs.value = value;
-    const text = asString(inner['text']);
-    if (text !== undefined)
-        performArgs.text = text;
-    if (toBox !== undefined)
-        performArgs.toBox = toBox;
-    try {
-        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 };
-    }
-    catch {
-        return {
-            result: undefined,
-            settled: false,
-            fellBack: true,
-            reason: InputModeReason.PROVIDER_ERROR,
-        };
-    }
-}
+import { sessionIdShape } from './tool-kit.js';
+import { asActionType, gradeOf } from './act-helpers.js';
+import { tryRealInput } from './real-input-attempt.js';
 /**
  * Narrow the wire's `action` to a real ActionType, or undefined.
  *
@@ -107,18 +37,29 @@ async function tryRealInput(deps, session, ref, action, args) {
  * as a generic failure rather than "that is not an action". Validate at the boundary, per the project's
  * unknown-plus-narrowing rule, so a typo is rejected where it can still be explained.
  */
+/**
+ * The action vocabulary, derived from ActionType — never retyped.
+ *
+ * The description used to list thirteen actions while ActionType had seventeen: blur, upload, drag
+ * and webmcp were real, callable, and undocumented, because a hand-copied list drifts the moment
+ * someone adds an arm. Deriving both the schema and the prose from the enum makes that impossible.
+ *
+ * The handler already refused an unknown action with a good message; the schema now refuses it
+ * one layer earlier, before any session is resolved or any work is done.
+ */
+const ACTION_TYPE_VALUES = Object.values(ActionType);
+const ACTION_TYPE_LIST = ACTION_TYPE_VALUES.join(' | ');
+const actionTypeEnum = z.enum(ACTION_TYPE_VALUES);
 export const ACT_TOOLS = [
     {
         name: ReticleTool.ACT,
         example: { ref: 'e42', action: 'fill', args: { value: 'hello' } },
-        description: 'Execute one action against a ref: click|dblclick|hover|focus|fill|type|clear|select|check|uncheck|submit|press|scrollIntoView. Returns immediately with a `since` cursor — observe the reaction with reticle_observe. Carries effect:{dispatched,targetMatched,visible,enabled,focusMoved,valueChanged,domMutatedWithin,occluded,occludedBy,scrolledIntoView} to tell "action missed" from "app didn\'t react"; dispatched=landed, settled=a real frame flushed, and a settle timeout never fails the tool. Fields at their uninformative default are OMITTED so a clean action collapses to its consequence: an absent dispatched/targetMatched/visible/enabled means true, an absent occluded/scrolledIntoView/valueChanged/defaultPrevented means false, an absent focusMoved/occludedBy means null. occluded=true means the click point is covered by another element (a real user could not click it) — synthetic dispatch still delivered the event; scrolledIntoView=true means an off-viewport target was scrolled in first. inputMode is "real" (native CDP, no synthetic effect block) or "synthetic"; clicks default to the occlusion-honest synthetic path even when CDP is configured — pass args.native:true to force a trusted native click (file pickers, clipboard). inputModeReason explains any real→synthetic choice so it is never silent. Full model (real-input, throttled tabs, `reticle drive`): docs/usage.md §18.',
+        description: 'Execute one action against a ref: click|dblclick|hover|focus|fill|type|clear|select|check|uncheck|submit|press|scrollIntoView. Returns immediately with a `since` cursor — observe the reaction with reticle_observe. For a VERDICT instead of a cursor use reticle_act_and_wait { until } — the same action plus the assertion, in one call; prefer it whenever the action is supposed to cause something. Carries effect:{dispatched,targetMatched,visible,enabled,focusMoved,valueChanged,domMutatedWithin,occluded,occludedBy,scrolledIntoView} to tell "action missed" from "app didn\'t react"; dispatched=landed, settled=a real frame flushed, and a settle timeout never fails the tool. Fields at their uninformative default are OMITTED so a clean action collapses to its consequence: an absent dispatched/targetMatched/visible/enabled means true, an absent occluded/scrolledIntoView/valueChanged/defaultPrevented means false, an absent focusMoved/occludedBy means null. occluded=true means the click point is covered by another element (a real user could not click it) — synthetic dispatch still delivered the event; scrolledIntoView=true means an off-viewport target was scrolled in first. inputMode is "real" (native CDP, no synthetic effect block) or "synthetic"; clicks default to the occlusion-honest synthetic path even when CDP is configured — pass args.native:true to force a trusted native click (file pickers, clipboard). inputModeReason explains any real→synthetic choice so it is never silent. Full model (real-input, throttled tabs, `reticle drive`): docs/usage.md §18.',
         inputSchema: {
             ref: z
                 .string()
                 .describe(`Element ref (e.g. 'e42') from reticle_snapshot/reticle_query — stable until the element leaves the DOM, so no re-snapshot between actions.`),
-            action: z
-                .string()
-                .describe('Action to perform: click | dblclick | hover | focus | fill | type | clear | select | check | uncheck | submit | press | scrollIntoView'),
+            action: actionTypeEnum.describe(`Action to perform: ${ACTION_TYPE_LIST}`),
             args: z
                 .record(z.unknown())
                 .optional()
@@ -163,10 +104,8 @@ export const ACT_TOOLS = [
                 return paused;
             refuseIfThrottled(session, args['refuseWhenThrottled']);
             const since = session.elapsed();
-            session.lastAct.markCursor(since); // honesty: wait_for/assert default their floor to this cursor
-            // Cleared up front: a throw between here and the result must not leave the PREVIOUS act's
-            // measurement standing, which would judge this window with the last one's evidence.
-            session.lastAct.markEffect(asString(args['action']), undefined);
+            // The act cursor + effect are marked only once the action has actually DISPATCHED (below, on
+            // each success path) — a refused act must leave nothing behind for the next observe to judge.
             const ref = asString(args['ref']) ?? '';
             // Open the journal's action-attribution window BEFORE dispatching, so it covers the native path
             // too. It used to open only on the synthetic path, and the native path returned above it — so a
@@ -181,10 +120,11 @@ export const ACT_TOOLS = [
                 // drive native pointer input when a provider is available; otherwise fall back.
                 const real = await tryRealInput(deps, session, ref, action, args);
                 if (real.result !== undefined) {
-                    if (deps.recordings.active().length > 0) {
-                        deps.recordings.capture(compileActStep(args, real.result));
-                    }
+                    captureAct(deps.recordings, args, real.result);
                     settledOutcome = real.settled ?? undefined;
+                    // Native input reports no synthetic effect block, so nothing measured in-target: undefined
+                    // (the weaker empty-window test), never a fabricated zero.
+                    session.lastAct.markActed(since, action, undefined);
                     return withControl(session, {
                         since,
                         inputMode: InputMode.REAL,
@@ -202,17 +142,15 @@ export const ACT_TOOLS = [
                 });
                 if (!result.ok)
                     throw new Error(result.error ?? 'act failed');
-                if (deps.recordings.active().length > 0) {
-                    deps.recordings.capture(compileActStep(args, result.result));
-                }
+                captureAct(deps.recordings, args, result.result);
                 // lift dispatch/settle status to the envelope (a settle timeout is NOT a failure).
                 const r = asRecord(result.result);
-                if (typeof r['settled'] === 'boolean')
+                if ('boolean' === typeof r['settled'])
                     settledOutcome = r['settled'];
                 // Keep what only this call measured, so the observe that judges this window can ask whether
                 // anything happened INSIDE the target — the one fact that separates a dead control from a
                 // page that was merely busy with something else.
-                session.lastAct.markEffect(asString(args['action']), mutatedWithin(r));
+                session.lastAct.markActed(since, action, mutatedWithin(r));
                 return withControl(session, {
                     since,
                     inputMode: InputMode.SYNTHETIC,
@@ -222,13 +160,13 @@ export const ACT_TOOLS = [
                     settled: r['settled'] ?? null,
                     settleReason: r['settleReason'] ?? null,
                     result: leanActResult(result.result),
-                    ...(real.fellBack === true ? { warning: ActionWarning.REAL_INPUT_FELL_BACK } : {}),
+                    ...(true === real.fellBack ? { warning: ActionWarning.REAL_INPUT_FELL_BACK } : {}),
                     ...healthEnvelope(session),
                 });
             }
             finally {
                 // Close the window on every exit (settle or throw), recording the action + settle outcome.
-                session.finishAction(undefined, settledOutcome, settledOutcome === true ? session.elapsed() - since : undefined);
+                session.finishAction(undefined, settledOutcome, true === settledOutcome ? session.elapsed() - since : undefined);
             }
         },
     },
@@ -258,12 +196,15 @@ export const ACT_TOOLS = [
             if (paused !== undefined)
                 return paused;
             const since = session.elapsed();
-            session.lastAct.markCursor(since); // honesty: a later wait_for/assert floors at this cursor
             session.beginAction(ReticleTool.ACT_SEQUENCE, asRecord(args));
             try {
                 const result = await session.command(ReticleCommand.ACT_SEQUENCE, { steps: args['steps'] });
                 if (!result.ok)
                     throw new Error(result.error ?? 'act_sequence failed');
+                // Marked only once the sequence ran: a refused sequence must leave no cursor behind for a
+                // later observe to judge. No single action and no in-target measurement here — per-step
+                // effects live in steps[] — so the effect is cleared rather than inherited from an earlier act.
+                session.lastAct.markActed(since, undefined, undefined);
                 if (deps.recordings.active().length > 0) {
                     deps.recordings.capture(compileSequenceStep(args, result.result));
                 }
@@ -283,7 +224,11 @@ export const ACT_TOOLS = [
     },
     {
         name: ReticleTool.ACT_AND_WAIT,
-        example: { ref: 'e42', action: 'click', until: { kind: 'signal', name: 'todos:loaded' } },
+        example: {
+            ref: 'e42',
+            action: 'click',
+            until: { kind: PredicateKind.SIGNAL, name: 'todos:loaded' },
+        },
         description: 'Act on a ref, then wait for a predicate to hold — one hop for the act->observe->assert loop. ' +
             'Omit `until` to wait for the page to settle (network + DOM idle) — use this instead of a fixed sleep. ' +
             'Returns { effect } (the action result), { verdict } (predicate pass/evidence/near-miss), ' +
@@ -294,13 +239,12 @@ export const ACT_TOOLS = [
             ref: z
                 .string()
                 .describe(`Element ref (e.g. 'e42') from reticle_snapshot/reticle_query — stable until the element leaves the DOM, so no re-snapshot between actions.`),
-            action: z
-                .string()
-                .describe('Action to perform: click | dblclick | hover | focus | fill | type | clear | select | check | uncheck | submit | press | scrollIntoView'),
+            action: actionTypeEnum.describe(`Action to perform: ${ACTION_TYPE_LIST}`),
             args: z
                 .record(z.unknown())
                 .optional()
                 .describe('Action-specific arguments: { value } for fill/select, { text } for type/press, { confirmDangerous: true } for a potentially destructive control.'),
+            predicate: PredicateSchema.optional().describe('Alias for `until` (the name reticle_assert / reticle_wait_for use).'),
             until: PredicateSchema.optional().describe('Predicate to wait for after the action completes (same shape as reticle_assert). OMIT to wait for the page to SETTLE — network + DOM idle — the deterministic default instead of a sleep. To assert a consequence AND settle, allOf them: { kind: "allOf", predicates: [<your predicate>, { kind: "settled" }] }.'),
             timeout_ms: z
                 .number()
@@ -374,26 +318,44 @@ export const ACT_TOOLS = [
         handler: async (deps, args) => {
             const session = deps.sessions.resolve(asString(args['sessionId']));
             // Live-control: refuse to drive the page (no act, no predicate eval) while paused.
+            //
+            // A VERDICT rides out with the refusal. This is the one tool here that promises `verified`,
+            // and the bare pause payload omitted it — so an agent reading `result.verified` got undefined
+            // from a call that carried no error, which is neither yes, no, nor unknown. It also broke this
+            // tool's own outputSchema, where `because` is required.
             const paused = pausedShortCircuit(session);
-            if (paused !== undefined)
-                return paused;
+            if (paused !== undefined) {
+                return { ...paused, verified: Verified.UNKNOWN, because: PAUSED_NO_VERDICT };
+            }
             refuseIfThrottled(session, args['refuseWhenThrottled']);
             // Omitting `until` waits for the page to settle (idle) — the deterministic default vs a sleep.
-            const until = args['until'] !== undefined
-                ? PredicateSchema.parse(args['until'])
-                : { kind: 'settled' };
+            // `predicate` is what reticle_assert / reticle_wait_for call this — see alias-args.ts.
+            const withUntil = aliasParam(args, 'until', ['predicate']);
+            const until = withUntil['until'] !== undefined
+                ? PredicateSchema.parse(withUntil['until'])
+                : { kind: PredicateKind.SETTLED };
             const timeout = asNumber(args['timeout_ms']) ?? DEFAULT_ASSERT_TIMEOUT_MS;
+            // Before anything is driven: this path cannot honour a native-input request, and taking the
+            // argument and ignoring it told the agent its trusted click had happened. See act-danger.
+            assertNativeInputSupported(asRecord(args['args']));
             const since = session.elapsed();
             // `dropped` is cumulative for the SESSION, so comparing against a pre-action reading is what
             // asks "did the buffer lose anything while THIS action was observed?" — the question the
             // honesty block means. Reading the raw total pinned every later verdict to `unknown` after a
             // single early eviction (measured on the Next.js demo at dropped:51, windows intact).
             const droppedBefore = session.bufferHealth().dropped;
-            session.lastAct.markCursor(since);
+            // The cursor + effect are marked after the act dispatches (below) — a refused act leaves none.
             // The attribution window stays open across the settle wait below, so post-dispatch async events
             // (the whole point of act_and_wait) attribute to this action. finishAction fires after the wait.
             session.beginAction(ReticleTool.ACT_AND_WAIT, asRecord(args));
             let settledOutcome;
+            // 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 honesty/already-true.
+            const alreadyTrue = until !== undefined && readsDomState(until)
+                ? (await evaluatePredicate(session, until, since, false)).pass
+                : false;
             try {
                 const actResult = await session.command(ReticleCommand.ACT, {
                     ref: args['ref'],
@@ -402,12 +364,16 @@ export const ACT_TOOLS = [
                 });
                 if (!actResult.ok)
                     throw new Error(actResult.error ?? 'act failed');
+                captureAct(deps.recordings, args, actResult.result);
+                // Dispatched — now this act owns the cursor and the effect. Marking its OWN measurement also
+                // stops the spread below from inheriting an earlier reticle_act's action and mutation count.
+                session.lastAct.markActed(since, asString(args['action']), mutatedWithin(asRecord(actResult.result)));
                 // Honesty: floor the predicate at this act's cursor so a stale buffered event can't satisfy it.
                 const verdict = timeout > 0
                     ? await waitForPredicate(session, until, timeout, since)
                     : await evaluatePredicate(session, until, since);
                 const r = asRecord(actResult.result);
-                if (typeof r['settled'] === 'boolean')
+                if ('boolean' === typeof r['settled'])
                     settledOutcome = r['settled'];
                 // Where the acted element is written. Captured at act time alongside the anchor, so it is
                 // available even when the action unmounted its own target.
@@ -442,7 +408,7 @@ export const ACT_TOOLS = [
                     grade: gradeOf(gradedLinks),
                     attribution: 'window',
                     truncated: session.bufferHealth().dropped > droppedBefore,
-                    coveragePartial: coverage.coverage === 'partial',
+                    coveragePartial: Coverage.PARTIAL === coverage.coverage,
                     ...(impeaching.note === undefined ? {} : { blindSpots: [impeaching.note] }),
                 });
                 const capsuleSaved = await saveFailedAssertCapsule({
@@ -467,6 +433,9 @@ export const ACT_TOOLS = [
                 const outcomeUnread = hasUnreadWriteOutcome(windowEvents);
                 const decision = decideVerified({
                     pass: verdict.pass,
+                    ...(alreadyTrue ? { alreadyTrue } : {}),
+                    // An assertion nobody could evaluate must not be reported as one the app failed.
+                    ...(verdict.inconclusive === undefined ? {} : { inconclusive: verdict.inconclusive }),
                     honesty,
                     contradictions,
                     ...(outcomePending ? { outcomePending } : {}),
@@ -505,7 +474,7 @@ export const ACT_TOOLS = [
                 });
             }
             finally {
-                session.finishAction(undefined, settledOutcome, settledOutcome === true ? session.elapsed() - since : undefined);
+                session.finishAction(undefined, settledOutcome, true === settledOutcome ? session.elapsed() - since : undefined);
             }
         },
     },

package/dist/tools/act-view.js

@@ -23,11 +23,11 @@ const NULL_NOISE = new Set(['occludedBy', 'focusMoved']);
 function leanEffect(effect) {
     const out = {};
     for (const [k, v] of Object.entries(effect)) {
-        if (TRUE_NOISE.has(k) && v === true)
+        if (TRUE_NOISE.has(k) && true === v)
             continue;
-        if (FALSE_NOISE.has(k) && v === false)
+        if (FALSE_NOISE.has(k) && false === v)
             continue;
-        if (NULL_NOISE.has(k) && v === null)
+        if (NULL_NOISE.has(k) && null === v)
             continue;
         out[k] = v;
     }
@@ -35,11 +35,11 @@ function leanEffect(effect) {
 }
 /** Return a copy of an act command result with its `effect` block leaned. Non-objects pass through. */
 export function leanActResult(result) {
-    if (result === null || typeof result !== 'object')
+    if (null === result || typeof result !== 'object')
         return result;
     const r = result;
     const effect = r['effect'];
-    if (effect === null || typeof effect !== 'object')
+    if (null === effect || typeof effect !== 'object')
         return result;
     return { ...r, effect: leanEffect(effect) };
 }
@@ -51,8 +51,8 @@ export function leanActResult(result) {
  */
 export function mutatedWithin(result) {
     const effect = result['effect'];
-    if (typeof effect !== 'object' || effect === null)
+    if (typeof effect !== 'object' || null === effect)
         return undefined;
     const value = effect['domMutatedWithin'];
-    return typeof value === 'number' ? value : 0;
+    return 'number' === typeof value ? value : 0;
 }

package/dist/tools/alias-args.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Accepting a neighbouring tool's spelling for the same parameter.
+ *
+ * Reticle's surface has a few places where one concept has two names, and every one of them is a
+ * rejected call for an agent that learned the other spelling from the tool next door:
+ *
+ *   reticle_act_and_wait { until }  vs  reticle_wait_for / reticle_assert { predicate }
+ *   reticle_annotate     { flow }   vs  every other flow tool          { flowName }
+ *
+ * Both cross a path the product prescribes — `act_and_wait` is the most-used tool, and
+ * `reticle_flow_save`'s own description tells the agent to go and call `reticle_annotate`.
+ *
+ * Aliasing, not renaming: the canonical name stays the contract, an explicit canonical value always
+ * wins, and a call carrying neither is left untouched so the schema error still names what was
+ * missing instead of being replaced by a guess.
+ */
+export declare function aliasParam(args: Record<string, unknown>, canonical: string, aliases: readonly string[]): Record<string, unknown>;

package/dist/tools/alias-args.js

@@ -0,0 +1,25 @@
+/**
+ * Accepting a neighbouring tool's spelling for the same parameter.
+ *
+ * Reticle's surface has a few places where one concept has two names, and every one of them is a
+ * rejected call for an agent that learned the other spelling from the tool next door:
+ *
+ *   reticle_act_and_wait { until }  vs  reticle_wait_for / reticle_assert { predicate }
+ *   reticle_annotate     { flow }   vs  every other flow tool          { flowName }
+ *
+ * Both cross a path the product prescribes — `act_and_wait` is the most-used tool, and
+ * `reticle_flow_save`'s own description tells the agent to go and call `reticle_annotate`.
+ *
+ * Aliasing, not renaming: the canonical name stays the contract, an explicit canonical value always
+ * wins, and a call carrying neither is left untouched so the schema error still names what was
+ * missing instead of being replaced by a guess.
+ */
+export function aliasParam(args, canonical, aliases) {
+    if (args[canonical] !== undefined)
+        return args;
+    for (const alias of aliases) {
+        if (args[alias] !== undefined)
+            return { ...args, [canonical]: args[alias] };
+    }
+    return args;
+}

package/dist/tools/assert-grade.js

@@ -10,18 +10,18 @@
  *
  * Pure: no IO, no clock.
  */
-import { isConsequenceKind, isPresenceKind } from '@reticlehq/core';
+import { isConsequenceKind, isPresenceKind, PredicateKind } from '@reticlehq/core';
 import { HonestyGrade } from '../honesty/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) {
-    if (predicate.kind === 'allOf' || predicate.kind === 'anyOf') {
+    if (PredicateKind.ALL_OF === predicate.kind || PredicateKind.ANY_OF === predicate.kind) {
         const subs = predicate.predicates.map(walk);
         return {
             consequence: subs.some((s) => s.consequence),
             presence: subs.some((s) => s.presence),
         };
     }
-    if (predicate.kind === 'not')
+    if (PredicateKind.NOT === predicate.kind)
         return walk(predicate.predicate);
     // 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.
@@ -50,12 +50,12 @@ export const DERIVED_IPC_STATUS_ADVICE = 'This asserts on a status code Reticle
  * Recognised by the `ipc://` scheme, so a genuine HTTP status is never second-guessed.
  */
 export function assertsDerivedIpcStatus(predicate) {
-    if (predicate.kind === 'allOf' || predicate.kind === 'anyOf') {
+    if (PredicateKind.ALL_OF === predicate.kind || PredicateKind.ANY_OF === predicate.kind) {
         return predicate.predicates.some(assertsDerivedIpcStatus);
     }
-    if (predicate.kind === 'not')
+    if (PredicateKind.NOT === predicate.kind)
         return assertsDerivedIpcStatus(predicate.predicate);
-    if (predicate.kind !== 'net')
+    if (predicate.kind !== PredicateKind.NET)
         return false;
     return (predicate.status !== undefined &&
         predicate.ok === undefined &&
@@ -74,11 +74,11 @@ export function isPresenceOnlyAssertion(predicate) {
  */
 export function gradeOfPredicate(predicate) {
     switch (predicate.kind) {
-        case 'signal':
+        case PredicateKind.SIGNAL:
             return HonestyGrade.SIGNAL;
-        case 'net':
+        case PredicateKind.NET:
             return HonestyGrade.NET;
-        case 'state':
+        case PredicateKind.STATE:
             return HonestyGrade.STATE;
         default:
             return HonestyGrade.PRESENCE;

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

@@ -14,7 +14,9 @@ import { type Contradiction } from '../events/contradictions.js';
  * consult it. Asserting a moment earlier — while the POST was still open — is the same story with a
  * different name: `request-never-settled`, also unreported.
  */
-export declare function assertVerdict(session: Session, predicate: Predicate, pass: boolean, since: number): Promise<{
+export declare function assertVerdict(session: Session, predicate: Predicate, pass: boolean, since: number, 
+/** Set when the assertion was never evaluated — see honesty/verified.ts. */
+inconclusive?: string): Promise<{
     decision: Record<string, unknown>;
     contradictions: Contradiction[];
     coverage: Record<string, unknown>;

package/dist/tools/assert-verdict.js

@@ -1,5 +1,5 @@
 import { findContradictions } from '../events/contradictions.js';
-import { blindSpotsFromState, buildCoverageStatement, impeachesCapture, } from '../honesty/blind-spots.js';
+import { blindSpotsFromState, buildCoverageStatement, Coverage, impeachesCapture, } from '../honesty/blind-spots.js';
 import { buildHonestyBlock } from '../honesty/honesty.js';
 import { hasAcceptedWrite } from '../honesty/accepted-write.js';
 import { hasUnreadWriteOutcome } from '../honesty/unread-outcome.js';
@@ -18,7 +18,9 @@ import { gradeOfPredicate } from './assert-grade.js';
  * consult it. Asserting a moment earlier — while the POST was still open — is the same story with a
  * different name: `request-never-settled`, also unreported.
  */
-export async function assertVerdict(session, predicate, pass, since) {
+export async function assertVerdict(session, predicate, pass, since, 
+/** Set when the assertion was never evaluated — see honesty/verified.ts. */
+inconclusive) {
     // Scope caveat, stated because it is a real limitation and not a bug: blind spots are tracked per
     // SESSION, not per assertion window, so a cross-origin iframe seen once marks every later verdict
     // in that session partial — including ones about a region it cannot affect. That errs toward
@@ -28,9 +30,9 @@ export async function assertVerdict(session, predicate, pass, since) {
     const statement = buildCoverageStatement(spots);
     // Omitted entirely when coverage is full, so an intact page pays nothing and the field's PRESENCE
     // is the warning.
-    const coverage = statement.coverage === 'partial'
+    const coverage = Coverage.PARTIAL === statement.coverage
         ? {
-            coverage: statement.note ?? 'partial',
+            coverage: statement.note ?? Coverage.PARTIAL,
             coverage_spots: statement.spots.map((sp) => ({ kind: sp.kind, count: sp.count })),
         }
         : {};
@@ -48,10 +50,11 @@ export async function assertVerdict(session, predicate, pass, since) {
     const outcomeUnread = hasUnreadWriteOutcome(windowEvents);
     const decision = decideVerified({
         pass,
+        ...(inconclusive === undefined ? {} : { inconclusive }),
         honesty: buildHonestyBlock({
             grade: gradeOfPredicate(predicate),
             attribution: 'window',
-            coveragePartial: statement.coverage === 'partial',
+            coveragePartial: Coverage.PARTIAL === statement.coverage,
             ...(impeaching.note === undefined ? {} : { blindSpots: [impeaching.note] }),
         }),
         contradictions,

package/dist/tools/browser-tools.js

@@ -1,4 +1,7 @@
 import { z } from 'zod';
+import { navigateResult } from './navigate-result.js';
+import { reloadResult } from './reload-result.js';
+import { waitForReconnect, RELOAD_RECONNECT_TIMEOUT_MS } from '../session/session-reconnect.js';
 import { ReticleCommand } from '@reticlehq/core';
 import { ReticleTool } from './tool-names.js';
 import { asString } from './tools-helpers.js';
@@ -7,7 +10,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). The SDK reconnects automatically after the page loads. Use reticle_sessions to confirm the new tab is connected before acting.',
+        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, not that the page arrived — the SDK is torn down by the navigation, so nothing can observe the new document. Call reticle_sessions to confirm a session reconnected at the new URL before acting.',
         inputSchema: {
             url: z.string().optional().describe('The URL to navigate to. Omit when using reload.'),
             reload: z
@@ -24,17 +27,36 @@ export const BROWSER_TOOLS = [
             ok: z.boolean(),
             url: z.string().optional(),
             reason: z.string().optional(),
+            // Present on a dispatched navigation: nothing here can see the new document, so arrival is
+            // reported as unconfirmed rather than implied by `ok`. See navigate-result.ts.
+            confirmed: z.boolean().optional(),
+            note: z.string().optional(),
         },
         handler: async (deps, args) => {
             // reload:true is the absorbed reticle_refresh — same command, one fewer advertised tool.
-            if (args['reload'] === true) {
+            if (true === args['reload']) {
+                const before = deps.sessions.resolve(asString(args['sessionId']));
                 await commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.REFRESH, {
-                    hard: args['hard'] === true,
+                    hard: true === args['hard'],
                 });
-                return { ok: true };
+                // WAIT for the page to come back, rather than telling the agent to. The id survives the
+                // reload, but the seconds between dispatch and the new HELLO are seconds in which every call
+                // lands in the old, disconnected session — measured as reticle_run failing 5 of 5 on a page
+                // that was healthy immediately afterwards. Returns on the first poll in the common case.
+                const back = await waitForReconnect({
+                    current: () => deps.sessions.get(before.id),
+                    previous: before,
+                    timeoutMs: RELOAD_RECONNECT_TIMEOUT_MS,
+                    now: deps.now,
+                    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+                });
+                // Not a bare `{ ok: true }`. The URL branch below already discloses that `ok` means
+                // DISPATCHED — the reload branch had identical semantics and said nothing, on the path most
+                // likely to need it. See reload-result.
+                return reloadResult(back);
             }
             const url = asString(args['url']);
-            if (url === undefined || url.length === 0)
+            if (url === undefined || 0 === url.length)
                 return { ok: false, reason: 'url required' };
             // Record navigate as an action. Its window is usually empty (the page unloads and the SDK
             // reconnects), but the action record itself — "navigated to X" — is the causal fact worth keeping.
@@ -42,11 +64,8 @@ export const BROWSER_TOOLS = [
             session.beginAction(ReticleTool.NAVIGATE, { url });
             try {
                 const result = (await commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.NAVIGATE, { url }));
-                return {
-                    ok: result.ok === true,
-                    ...(typeof result.url === 'string' ? { url: result.url } : {}),
-                    ...(typeof result.reason === 'string' ? { reason: result.reason } : {}),
-                };
+                // `ok` is the browser accepting the instruction, not the page arriving — see navigate-result.
+                return navigateResult(result);
             }
             finally {
                 session.finishAction();
@@ -68,7 +87,7 @@ export const BROWSER_TOOLS = [
         },
         handler: async (deps, args) => {
             await commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.REFRESH, {
-                hard: args['hard'] === true,
+                hard: true === args['hard'],
             });
             return { ok: true };
         },