@reticlehq/server 2.4.0 → 2.5.0

package/dist/telemetry/verification-of.js

@@ -0,0 +1,84 @@
+/**
+ * Which tool results count as a completed verification, as one pure rule.
+ *
+ * It used to live inline in `runTool` and read `status === 'pass'`, mapping everything else to
+ * "no verdict". That was wrong in both directions at once, and the shape of the error is visible in
+ * the production data:
+ *
+ *   - a FAILING suite emitted nothing, so `verification_completed` only ever fired on greens while
+ *     `bugsInResult` fired on the reds — bugs with no verifications to divide them by;
+ *   - an EMPTY suite ("all 0 flows pass") emitted `verified: yes, passed: true`.
+ *
+ * Extracted because a rule this easy to get wrong, feeding the one number shown to investors, should
+ * be readable and testable on its own rather than inferred from a ternary inside a dispatcher.
+ */
+import { VerifiedReason } from '@reticlehq/core';
+import { VERIFICATION_TOOLS } from '../tools/feedback-tools.js';
+import { getBrowserMode } from './browser-mode.js';
+/**
+ * The deciding clause, read off the result `decideVerified` wrote it onto.
+ *
+ * Narrowed against core's own list rather than forwarded: a result is an untyped record here, and a
+ * value that is not a member is not a reason — absent beats a string nobody can group by. Derived
+ * from the enum, never re-listed, so a new clause is covered the day it exists.
+ */
+const REASONS = new Set(Object.values(VerifiedReason));
+function reasonOf(result) {
+    const raw = result['verifiedReason'];
+    return 'string' === typeof raw && REASONS.has(raw) ? raw : undefined;
+}
+/** Suite statuses. `unverifiable` is a suite that ran but proved nothing — including an empty one. */
+const SuiteStatus = {
+    PASS: 'pass',
+    FAIL: 'fail',
+};
+/**
+ * The verification payload for a result, or undefined when nothing was verified.
+ *
+ * `falseGreenCaught` is the one that matters: the assertion PASSED and Reticle still refused to call
+ * it verified. That is the product's thesis reduced to a boolean.
+ */
+export function verificationOf(toolName, result, durationMs, brand) {
+    if (!VERIFICATION_TOOLS.has(toolName))
+        return undefined;
+    // A paused session REFUSES the call — nothing driven, nothing asserted. The refusal carries a
+    // verdict field so the agent never reads undefined off it, and that field must not be mistaken
+    // here for work that happened.
+    if (true === result['paused'])
+        return undefined;
+    const verified = 'string' === typeof result['verified'] ? result['verified'] : undefined;
+    // flow_verify reports `status: pass|fail|unverifiable`; assert reports a boolean `pass`. Accept
+    // either shape so the whole family is covered without normalizing four tools' contracts for a
+    // metric's convenience — but a status that is neither pass nor fail is NOT a verdict, and an empty
+    // suite reports exactly that.
+    const status = result['status'];
+    const passed = 'boolean' === typeof result['pass']
+        ? result['pass']
+        : status === SuiteStatus.PASS
+            ? true
+            : status === SuiteStatus.FAIL
+                ? false
+                : undefined;
+    if (verified === undefined && passed === undefined)
+        return undefined;
+    const reason = reasonOf(result);
+    return {
+        via: toolName,
+        verified: verified ?? (true === passed ? 'yes' : 'no'),
+        passed: passed ?? 'yes' === verified,
+        falseGreenCaught: true === passed && 'no' === verified,
+        durationMs,
+        // Headless CI, a human watching, or somebody's own dev server — three different products behind
+        // one number until this was recorded.
+        browser: getBrowserMode(),
+        // WHICH browser, when the page said. `attached` is the common case and says only that Reticle
+        // launched nothing; the brand is the difference between "somebody's own browser" and knowing it
+        // was Edge. Omitted when unreported — a desktop webview and an older SDK both have no answer,
+        // and "unknown" would be a value on a dashboard rather than a gap.
+        ...(brand !== undefined ? { brand } : {}),
+        // WHY, not just what. `verified: unknown` covered seven different clauses of the honesty rule
+        // belonging to three different owners — the agent, the app, and Reticle's own blind spots — and
+        // they need opposite responses. A suite verdict has no clause behind it and reports none.
+        ...(reason === undefined ? {} : { reason }),
+    };
+}

package/dist/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 } from '../capsule/capsule-store.js';
+import { CapsuleStore, capsuleId, CAPSULE_VERSION } from '../capsule/capsule-store.js';
 import { ReticleTool } from './tool-names.js';
 import { asRecord, asString } from './tools-helpers.js';
 /** Returns the capsule id when one was written, or undefined when there was nothing to save. */
@@ -23,7 +23,7 @@ export async function saveFailedAssertCapsule(inputs) {
         .map((l) => ('name' in l ? `${l.kind} ${String(l.name)}` : l.kind))
         .join(' AND ');
     const saved = await new CapsuleStore(deps.fs, deps.reticleRoot).save({
-        version: 1,
+        version: CAPSULE_VERSION,
         id,
         createdAt: deps.now(),
         origin: 'failed-assert',

package/dist/tools/act-danger.d.ts

@@ -5,3 +5,15 @@ export declare function assertNotDestructive(action: ActionType, innerArgs: Reco
  * source alone never says so.
  */
 export declare function assertDragNotDestructive(innerArgs: Record<string, unknown>, from: unknown, to: unknown): void;
+/**
+ * `reticle_act_and_wait` cannot drive native input, and used to take `args.native` and ignore it.
+ *
+ * An open `args` passthrough accepted the field, the handler drove the page through the SDK anyway,
+ * and the result claimed success — so an agent asking for the one thing a synthetic click cannot do
+ * (a file picker, the clipboard, an `isTrusted`-gated handler) got a synthetic click and no hint
+ * that its request had been dropped. A silently ignored argument is a false promise; refusing with
+ * the route that DOES work is the honest answer.
+ */
+export declare const NATIVE_INPUT_UNSUPPORTED: string;
+/** Refuse rather than silently drop a native-input request the act-then-wait path cannot honour. */
+export declare function assertNativeInputSupported(innerArgs: Record<string, unknown>): void;

package/dist/tools/act-danger.js

@@ -1,4 +1,4 @@
-import { ActionType, DANGEROUS_ACTION_CONFIRM_ARG, isDangerousActionText } from '@reticlehq/core';
+import { ActionType, DANGEROUS_ACTION_CONFIRM_ARG, NATIVE_INPUT_ARG, isDangerousActionText, } from '@reticlehq/core';
 import { asRecord, asString } from './tools-helpers.js';
 /**
  * Refuse to drive a money-moving or destructive control by accident.
@@ -25,7 +25,7 @@ function descriptorText(value) {
 export function assertNotDestructive(action, innerArgs, inspected) {
     if (action !== ActionType.CLICK && action !== ActionType.DBLCLICK)
         return;
-    if (innerArgs[DANGEROUS_ACTION_CONFIRM_ARG] === true)
+    if (true === innerArgs[DANGEROUS_ACTION_CONFIRM_ARG])
         return;
     if (!isDangerousActionText(descriptorText(inspected)))
         return;
@@ -36,9 +36,26 @@ export function assertNotDestructive(action, innerArgs, inspected) {
  * source alone never says so.
  */
 export function assertDragNotDestructive(innerArgs, from, to) {
-    if (innerArgs[DANGEROUS_ACTION_CONFIRM_ARG] === true)
+    if (true === innerArgs[DANGEROUS_ACTION_CONFIRM_ARG])
         return;
     if (!isDangerousActionText(`${descriptorText(from)} ${descriptorText(to)}`))
         return;
     throw new Error(`potentially destructive native action blocked; retry with args.${DANGEROUS_ACTION_CONFIRM_ARG}=true`);
 }
+/**
+ * `reticle_act_and_wait` cannot drive native input, and used to take `args.native` and ignore it.
+ *
+ * An open `args` passthrough accepted the field, the handler drove the page through the SDK anyway,
+ * and the result claimed success — so an agent asking for the one thing a synthetic click cannot do
+ * (a file picker, the clipboard, an `isTrusted`-gated handler) got a synthetic click and no hint
+ * that its request had been dropped. A silently ignored argument is a false promise; refusing with
+ * the route that DOES work is the honest answer.
+ */
+export const NATIVE_INPUT_UNSUPPORTED = `reticle_act_and_wait cannot drive native input, so args.${NATIVE_INPUT_ARG} would be ignored. ` +
+    `Use reticle_act { args: { ${NATIVE_INPUT_ARG}: true } } for the trusted click, then assert the ` +
+    'consequence with reticle_assert / reticle_observe using the `since` cursor it returns.';
+/** Refuse rather than silently drop a native-input request the act-then-wait path cannot honour. */
+export function assertNativeInputSupported(innerArgs) {
+    if (true === innerArgs[NATIVE_INPUT_ARG])
+        throw new Error(NATIVE_INPUT_UNSUPPORTED);
+}

package/dist/tools/act-helpers.js

@@ -5,16 +5,16 @@
  * session, a command, or a tool definition — these are total functions over their arguments, which
  * is why they can be tested without a browser and why they were the right thing to move.
  */
-import { ActionType } from '@reticlehq/core';
+import { ActionType, ConsequenceKind } from '@reticlehq/core';
 import { HonestyGrade } from '../honesty/honesty.js';
 import { asNumber, asRecord, asString } from './tools-helpers.js';
 /** The strongest consequence grade a set of expected links proves (signal > net > state > presence). */
 export function gradeOf(links) {
-    if (links.some((l) => l.kind === 'signal'))
+    if (links.some((l) => ConsequenceKind.SIGNAL === l.kind))
         return HonestyGrade.SIGNAL;
-    if (links.some((l) => l.kind === 'net'))
+    if (links.some((l) => ConsequenceKind.NET === l.kind))
         return HonestyGrade.NET;
-    if (links.some((l) => l.kind === 'state'))
+    if (links.some((l) => ConsequenceKind.STATE === l.kind))
         return HonestyGrade.STATE;
     return HonestyGrade.PRESENCE;
 }

package/dist/tools/act-tools.d.ts

@@ -1,10 +1,2 @@
 import { type ToolDef } from './tool-kit.js';
-/**
- * Narrow the wire's `action` to a real ActionType, or undefined.
- *
- * It used to be `asString(args['action']) ?? ''`, so an unknown or missing action became the empty
- * string and travelled on — reaching the browser as a command it could not perform, and reported back
- * 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.
- */
 export declare const ACT_TOOLS: ToolDef[];

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>;