@reticlehq/server 2.6.0 → 2.8.0

package/dist/telemetry/verification-of.js

@@ -12,7 +12,7 @@
  * 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 { CaptureLoss, VerifiedReason } from '@reticlehq/core';
 import { VERIFICATION_TOOLS } from '../tools/feedback-tools.js';
 import { getBrowserMode } from './browser-mode.js';
 /**
@@ -27,11 +27,64 @@ function reasonOf(result) {
     const raw = result['verifiedReason'];
     return 'string' === typeof raw && REASONS.has(raw) ? raw : undefined;
 }
+/**
+ * WHICH loss made the capture unclean, read off the honesty block the verdict already carries.
+ *
+ * Narrowed against core's own list for the same reason `reasonOf` is: a value that is not a member
+ * is not an answer. Reported as `OTHER` rather than dropped when the block says the capture was
+ * dirty and names no kind — the loss is real either way, and a silent absence there would read as
+ * "no unclean verdicts happened", which is the opposite of the truth.
+ */
+const LOSSES = new Set(Object.values(CaptureLoss));
+function uncleanLossOf(result, reason) {
+    if (VerifiedReason.UNCLEAN_CAPTURE !== reason)
+        return undefined;
+    const honesty = result['honesty'];
+    const integrity = null !== honesty && 'object' === typeof honesty
+        ? honesty.integrity
+        : undefined;
+    const first = Array.isArray(integrity?.losses) ? integrity.losses[0] : undefined;
+    return 'string' === typeof first && LOSSES.has(first)
+        ? first
+        : CaptureLoss.OTHER;
+}
 /** Suite statuses. `unverifiable` is a suite that ran but proved nothing — including an empty one. */
 const SuiteStatus = {
     PASS: 'pass',
     FAIL: 'fail',
 };
+/**
+ * Did the assertion itself pass, across three tool shapes that spell it three ways.
+ *
+ * `reticle_assert` spreads its verdict at the top level, so `pass` is right there. `flow_verify`
+ * reports a suite `status`. **`reticle_act_and_wait` nests it under `verdict`**, and that omission is
+ * why `falseGreenCaught` had never once been true in the field: `passed` came back `undefined` for
+ * every act_and_wait, so `true === passed` was false whatever the app did, on the one tool the
+ * product tells agents to reach for first.
+ *
+ * The metric it feeds is the product's central claim reduced to a boolean, and it was structurally
+ * unable to fire on the flagship path. Worse, the test file pinned that: one case used the real
+ * nested shape and asserted `falseGreenCaught: false`, directly beneath a comment calling this case
+ * "the thesis", while the case that asserted `true` used a flat shape act_and_wait never emits.
+ *
+ * A permanently-zero metric is indistinguishable from a working one that has nothing to report, so
+ * nobody could have noticed this from the data. It took reading the emit path.
+ */
+function passedOf(result, status) {
+    if ('boolean' === typeof result['pass'])
+        return result['pass'];
+    const verdict = result['verdict'];
+    if (null !== verdict && 'object' === typeof verdict) {
+        const nested = verdict['pass'];
+        if ('boolean' === typeof nested)
+            return nested;
+    }
+    if (status === SuiteStatus.PASS)
+        return true;
+    if (status === SuiteStatus.FAIL)
+        return false;
+    return undefined;
+}
 /**
  * The verification payload for a result, or undefined when nothing was verified.
  *
@@ -52,20 +105,28 @@ export function verificationOf(toolName, result, durationMs, brand) {
     // 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;
+    const passed = passedOf(result, status);
     if (verified === undefined && passed === undefined)
         return undefined;
     const reason = reasonOf(result);
+    const uncleanLoss = uncleanLossOf(result, reason);
     return {
         via: toolName,
         verified: verified ?? (true === passed ? 'yes' : 'no'),
         passed: passed ?? 'yes' === verified,
+        // The assertion passed and Reticle answered `no` anyway: a green actively refuted.
+        //
+        // Deliberately NOT widened to every refusal of a passing assertion, though several of them are
+        // arguably false greens caught too. `decideVerified` refuses a green seven ways and only
+        // `contradicted` answers `no`; the rest answer `unknown` on purpose, because UNKNOWN must never
+        // collapse into NO. `already_true` is the tempting one: a green that proved nothing because the
+        // condition already held before the action, found by a check built for exactly that.
+        //
+        // It stays out because `reason` is on this same payload. Anyone who wants the wider number can
+        // count it without a definition change, and a definition that shifts underneath a metric is
+        // worse than one that is narrow, because the old and new series look comparable and are not.
+        // Widening it would also have landed in the same release as the fix above, making it impossible
+        // to tell how much of any rise was the bug and how much was the redefinition.
         falseGreenCaught: true === passed && 'no' === verified,
         durationMs,
         // Headless CI, a human watching, or somebody's own dev server — three different products behind
@@ -80,5 +141,8 @@ export function verificationOf(toolName, result, durationMs, brand) {
         // 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 }),
+        // WHAT was lost, when the reason was that something was. Three owners, three fixes, one bar
+        // until now.
+        ...(uncleanLoss === undefined ? {} : { uncleanLoss }),
     };
 }

package/dist/temp-dir.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Removing a temp directory on Windows, without inventing a product failure.
+ *
+ * `rm(dir, { recursive: true, force: true })` is the obvious teardown and it is not enough on
+ * Windows. Deletion there is not immediate: a handle the OS, the indexer or a virus scanner still
+ * holds keeps the entry alive for a moment after the last close, so the directory is observed
+ * non-empty at the instant `rmdir` runs and Node throws `ENOTEMPTY`. `force` does not cover it —
+ * that suppresses "missing", not "busy".
+ *
+ * The failure lands in `afterEach`, so it is reported against the test that just PASSED, and the
+ * leftover directory then bleeds state into what runs next. On CI this presented as five failures in
+ * one file, four of them consequential and one of them the wonderfully misleading "expected length 1
+ * but got 2" — a fake production bug manufactured entirely by teardown. This repo already has that
+ * exact story written up in `project-store.test.ts` about a timed-out test's stray writes; this is the
+ * same failure arriving through the filesystem instead of through the clock.
+ *
+ * `maxRetries`/`retryDelay` exist in Node for precisely this, and are documented as Windows-oriented.
+ * They are a no-op on POSIX, where the first attempt already succeeds.
+ */
+/**
+ * Delete a temp directory tree, tolerating Windows' delayed handle release.
+ *
+ * Never throws: a temp directory that outlives the test is the operating system's problem, not a
+ * reason to fail a run or to report a defect the product does not have. What must not happen is the
+ * opposite — a red that says nothing about the code under test.
+ */
+export declare function removeTempDir(dir: string): Promise<void>;

package/dist/temp-dir.js

@@ -0,0 +1,46 @@
+/**
+ * Removing a temp directory on Windows, without inventing a product failure.
+ *
+ * `rm(dir, { recursive: true, force: true })` is the obvious teardown and it is not enough on
+ * Windows. Deletion there is not immediate: a handle the OS, the indexer or a virus scanner still
+ * holds keeps the entry alive for a moment after the last close, so the directory is observed
+ * non-empty at the instant `rmdir` runs and Node throws `ENOTEMPTY`. `force` does not cover it —
+ * that suppresses "missing", not "busy".
+ *
+ * The failure lands in `afterEach`, so it is reported against the test that just PASSED, and the
+ * leftover directory then bleeds state into what runs next. On CI this presented as five failures in
+ * one file, four of them consequential and one of them the wonderfully misleading "expected length 1
+ * but got 2" — a fake production bug manufactured entirely by teardown. This repo already has that
+ * exact story written up in `project-store.test.ts` about a timed-out test's stray writes; this is the
+ * same failure arriving through the filesystem instead of through the clock.
+ *
+ * `maxRetries`/`retryDelay` exist in Node for precisely this, and are documented as Windows-oriented.
+ * They are a no-op on POSIX, where the first attempt already succeeds.
+ */
+import { rm } from 'node:fs/promises';
+/**
+ * Retries and backoff. Small and bounded: this is covering a millisecond-scale handle release, so if
+ * it has not gone in half a second the cause is not a race and a slower retry would only hide it.
+ */
+const MAX_RETRIES = 10;
+const RETRY_DELAY_MS = 50;
+/**
+ * Delete a temp directory tree, tolerating Windows' delayed handle release.
+ *
+ * Never throws: a temp directory that outlives the test is the operating system's problem, not a
+ * reason to fail a run or to report a defect the product does not have. What must not happen is the
+ * opposite — a red that says nothing about the code under test.
+ */
+export async function removeTempDir(dir) {
+    try {
+        await rm(dir, {
+            recursive: true,
+            force: true,
+            maxRetries: MAX_RETRIES,
+            retryDelay: RETRY_DELAY_MS,
+        });
+    }
+    catch {
+        // Deliberately swallowed — see above. The OS reclaims the temp directory regardless.
+    }
+}

package/dist/tools/act-tools.js

@@ -6,7 +6,7 @@
 import { z } from 'zod';
 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 { ActionType, ActionWarning, CaptureLoss, 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';
@@ -14,8 +14,11 @@ import { buildReactionReport, summarizeReaction } from '../events/reaction.js';
 import { parsePredicate } from '../events/predicate-parse.js';
 import { causalSummary } from '../capsule/causal-summary.js';
 import { findContradictions } from '../events/contradictions.js';
+import { inFlightRequestLabels, waitForInFlight } from './settle-in-flight.js';
+import { waitForReaction } from './react-grace.js';
 import { decideVerified } from '../honesty/verified.js';
 import { readsDomState } from '../honesty/already-true.js';
+import { describeWaitTarget } from '../honesty/unsettled.js';
 import { saveFailedAssertCapsule } from './act-capsule.js';
 import { buildDivergenceCapsule } from '../capsule/capsule.js';
 import { predicateToExpectedLinks } from '../capsule/predicate-to-links.js';
@@ -55,7 +58,7 @@ export const ACT_TOOLS = [
     {
         name: ReticleTool.ACT,
         example: { ref: 'e42', action: 'fill', args: { value: 'hello' } },
-        description: 'Act WITHOUT checking the result — if the action is supposed to cause something, use reticle_act_and_wait { until } instead and get the verdict in the same call. This tool returns immediately with a `since` cursor; observe the reaction yourself with reticle_observe. Use it for actions with no observable consequence to assert (focus, hover, scrollIntoView, a fill you are about to submit). One action against a ref: click|dblclick|hover|focus|fill|type|clear|select|check|uncheck|submit|press|scrollIntoView. 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). args.holdMs keeps the pointer DOWN for that long between mousedown and mouseup — the only way to drive a hold-to-confirm control (hold-to-delete, hold-to-record, long-press); effect.heldMs reports the hold actually achieved, which a throttled background tab can stretch. args.confirmDangerous is a permission gate and NOT a duration: it allows a destructive control, it does not hold one. inputModeReason explains any real→synthetic choice so it is never silent. Full model (real-input, throttled tabs, `reticle drive`): docs/usage.md §18.',
+        description: 'Act WITHOUT checking the result — if the action is supposed to cause something, use reticle_act_and_wait { until } instead and get the verdict in the same call. This tool returns immediately with a `since` cursor; observe the reaction yourself with reticle_observe. Use it for actions with no observable consequence to assert (focus, hover, scrollIntoView, a fill you are about to submit). One action against a ref: click|dblclick|hover|focus|fill|type|clear|select|check|uncheck|submit|press|scrollIntoView. 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). args.holdMs keeps the pointer DOWN for that long between mousedown and mouseup — the only way to drive a hold-to-confirm control (hold-to-delete, hold-to-record, long-press); effect.heldMs reports the hold actually achieved, which a throttled background tab can stretch. args.confirmDangerous is a permission gate and NOT a duration: it allows a destructive control, it does not hold one. inputModeReason explains any real→synthetic choice so it is never silent. Full model (real-input, throttled tabs, `reticle drive`): node_modules/@reticlehq/server/docs/usage.md §18.',
         inputSchema: {
             ref: z
                 .string()
@@ -64,7 +67,7 @@ export const ACT_TOOLS = [
             args: z
                 .record(z.unknown())
                 .optional()
-                .describe('Action-specific arguments: { value } for fill/select, { text } for type/press, { native: true } to force a trusted native click, { holdMs: N } to keep the pointer DOWN for N ms (hold-to-confirm controls; effect.heldMs reports what was achieved), { confirmDangerous: true } to allow a potentially destructive control — a permission gate, NOT a duration.'),
+                .describe('Action-specific arguments: { value } for fill/select, { text } for type/press (the key NAME, e.g. Escape or Tab), { toRef } for drag (the ref to drop ON — without it the drag lands nowhere), { native: true } to force a trusted native click, { holdMs: N } to keep the pointer DOWN for N ms (hold-to-confirm controls; effect.heldMs reports what was achieved), { confirmDangerous: true } to allow a potentially destructive control — a permission gate, NOT a duration.'),
             refuseWhenThrottled: z
                 .boolean()
                 .optional()
@@ -255,7 +258,7 @@ export const ACT_TOOLS = [
             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.'),
+                .describe('Action-specific arguments: { value } for fill/select, { text } for type/press (the key NAME, e.g. Escape or Tab), { toRef } for drag (the ref to drop ON — without it the drag lands nowhere), { 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
@@ -295,7 +298,7 @@ export const ACT_TOOLS = [
                 .describe('Reaction digest: { window_ms, summary } of what the app did (DOM/network/route/console/signal counts). The full per-event timeline is one reticle_observe { since } away.'),
             summary: z
                 .unknown()
-                .describe('Bounded causal summary: net {total,errors,headline}, consoleErrors, statePathsChanged, storageKeysChanged, stateDiffs [{path,from,to}], storageDiffs [{key,from,to}], route, signals, layoutShift, longTasks — real before→after diffs (capped), not just readings.'),
+                .describe('Bounded causal summary: net {total,errors,headline}, consoleErrors, statePathsChanged, storageKeysChanged, stateDiffs [{path,from,to}], storageDiffs [{key,from,to}], route, signals, layoutShift, longTasks — real before→after diffs (capped), not just readings. Every list is length-capped so the verdict can never be the field a client truncates; `elided` says which lists lost entries and how many.'),
             // Promoted out of `effect` on RED only — the file:line the failure came from, the first thing a
             // repair wants. Undeclared, it was stripped on the validating profile exactly like the structured
             // cause above was, losing the highest-value pointer on the one path (a failed verdict) that has it.
@@ -355,11 +358,6 @@ export const ACT_TOOLS = [
             // 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;
             // 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.
@@ -385,9 +383,39 @@ export const ACT_TOOLS = [
                 // 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 predicateStarted = session.elapsed();
                 const verdict = timeout > 0
                     ? await waitForPredicate(session, until, timeout, since)
                     : await evaluatePredicate(session, until, since);
+                // The predicate resolves the INSTANT it holds, which on an optimistically-navigating app is
+                // while the write is still in flight — so the verdict was taken over a window the app had not
+                // finished, and came back `unknown / unsettled` asking the CALLER to re-check. A login that
+                // genuinely succeeded returned at 492ms of an 8000ms budget with every corroborating channel
+                // agreeing. Spend the rest of the budget the caller already granted.
+                //
+                // This decides nothing: it waits for the answer instead of guessing at it. A response that
+                // arrives as a FAILURE still contradicts — and now arrives INSIDE the window, where the
+                // detector can see it at all — while a request still open when the budget genuinely runs out
+                // reports unsettled exactly as before, an honest limit rather than an early exit. Costs
+                // nothing on the common path, where no request is in flight.
+                if (verdict.pass && timeout > 0) {
+                    const sleep = {
+                        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+                    };
+                    const spent = () => timeout - (session.elapsed() - predicateStarted);
+                    await waitForInFlight(session, since, spent(), sleep);
+                    // Waiting for the response moved the hazard rather than removing it: the response now lands
+                    // inside the window BY DESIGN, and the app's re-render happens a task or two later. Close
+                    // the window in that gap and every channel agrees the app took a successful write and did
+                    // nothing — `response-ignored`, i.e. `verified:"no"` on a correct app, produced entirely by
+                    // where we stopped looking. A false accusation is the more damaging direction of error for
+                    // a verification tool: it sends someone to fix code that is not broken.
+                    //
+                    // So the response is not the end of the window; the app's REACTION to it is. Paid only in
+                    // the shape that would otherwise be accused — a successful mutating write with nothing
+                    // moved after it — and short enough that a genuinely dropped response is still reported.
+                    await waitForReaction(session, since, spent(), sleep);
+                }
                 const r = asRecord(actResult.result);
                 if ('boolean' === typeof r['settled'])
                     settledOutcome = r['settled'];
@@ -427,12 +455,28 @@ export const ACT_TOOLS = [
                 // whose own words were "over a clean capture".
                 const gapNote = transportGapNote(windowEvents);
                 const impeachingNotes = [impeaching.note, gapNote].filter((n) => n !== undefined);
+                const bufferLost = session.lostSince(since);
+                // Which loss, as an enum, beside the prose that describes it. Classified here because this is
+                // the only place that knows the three apart: our buffer, our transport, and the page's own
+                // boundaries. See `CaptureLoss`.
+                const losses = [
+                    ...(bufferLost ? [CaptureLoss.BUFFER_LOSS] : []),
+                    ...(gapNote === undefined ? [] : [CaptureLoss.TRANSPORT_GAP]),
+                    ...(impeaching.note === undefined ? [] : [CaptureLoss.BLIND_SPOT]),
+                ];
                 const honesty = buildHonestyBlock({
                     grade: gradeOf(gradedLinks),
                     attribution: 'window',
-                    truncated: session.bufferHealth().dropped > droppedBefore,
+                    // Did the buffer lose scarce evidence FROM THIS WINDOW — not "did it evict anything while
+                    // the action ran", which was the previous rule and which is true on essentially every live
+                    // page. Age eviction retires everything past 60s on every push, and the churn floor is
+                    // sacrificed on purpose; neither costs this verdict a single event it needed. In the
+                    // field this made `unclean_capture` the dominant cause of `unknown`, reported for
+                    // evictions that happened outside the window they impeached.
+                    truncated: bufferLost,
                     coveragePartial: Coverage.PARTIAL === coverage.coverage,
                     ...(0 === impeachingNotes.length ? {} : { blindSpots: impeachingNotes }),
+                    losses,
                 });
                 const capsuleSaved = await saveFailedAssertCapsule({
                     deps,
@@ -446,8 +490,23 @@ export const ACT_TOOLS = [
                 // Pass the action: an EMPTY window then reads as "the target does not react" rather than as a
                 // clean run — `settled` is satisfied by a page that did nothing, i.e. by a click that missed.
                 const acted = asString(args['action']);
+                // `prior` matters here for the same reason it matters on the assert path: a SCALE error
+                // disagrees with a value the API stated EARLIER in the session, which an action-scoped
+                // window can never contain. Without it `unit-mismatch` — the money false green, where a
+                // total renders 100x off — is structurally unreachable from `act_and_wait`, which is the
+                // tool the product tells agents to reach for first. Our best detector could not fire on our
+                // flagship path, and nothing said so: the finding was simply never produced.
+                //
+                // Learning material only. Attribution is unchanged — findings still come exclusively from
+                // `windowEvents`, exactly as on the assert path.
+                const prior = since > 0 ? (await session.queryEvents({ since: 0 })).filter((e) => e.t < since) : [];
+                //
+                // `actionSince` is the window's own floor here, which is the tightest attribution there is —
+                // and it is what lets `duplicate-request` claim "one user action was performed" and mean it.
                 const contradictions = findContradictions(windowEvents, {
                     action: acted,
+                    prior,
+                    actionSince: since,
                     ...session.lastAct.effect(),
                 });
                 // The single field an agent reads. Everything below it is the evidence it was derived from;
@@ -470,6 +529,13 @@ export const ACT_TOOLS = [
                     // `settled` is genuinely optional: a wait that declared no predicate never measured it, and
                     // passing `false` there would report "never settled" about something never asked to settle.
                     ...(settledOutcome === undefined ? {} : { settled: settledOutcome }),
+                    // What the wait was for and what was still outstanding when it ended. Read only by the
+                    // UNSETTLED clauses; supplied always because both of them are reachable from here and the
+                    // window is already in hand.
+                    unsettled: {
+                        waitedFor: describeWaitTarget(until),
+                        stillInFlight: inFlightRequestLabels(windowEvents),
+                    },
                 });
                 return withControl(session, {
                     ...decision,

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

@@ -12,7 +12,7 @@
  */
 import { HonestyGrade } from '../honesty/honesty.js';
 import type { Predicate } from '../events/predicate.js';
-export declare 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 \u2014 or allOf it with one \u2014 so green means the feature actually worked.";
+export declare 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.";
 /**
  * True when the predicate asserts ONLY element/text presence with no signal/net consequence anywhere
  * — the weak pattern worth nudging. A predicate that mixes in a consequence, or that checks something

package/dist/tools/assert-grade.js

@@ -12,24 +12,46 @@
  */
 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) {
+export const PRESENCE_ONLY_ADVICE = 'This predicate only checks element/text presence, not an observable consequence. A locator healed to the wrong element (or a stale render) can satisfy it while the feature is broken. Prefer a { signal } or { net } assertion (or allOf it with one) so green means the feature actually worked.';
+function walk(predicate, negated = false) {
     if (PredicateKind.ALL_OF === predicate.kind || PredicateKind.ANY_OF === predicate.kind) {
-        const subs = predicate.predicates.map(walk);
+        const subs = predicate.predicates.map((p) => walk(p, negated));
         return {
             consequence: subs.some((s) => s.consequence),
             presence: subs.some((s) => s.presence),
         };
     }
+    // Under a NOT, checking content strengthens nothing, so the exemption below must not apply. The
+    // nudge warns that a healed or wrong locator can satisfy the predicate, and for an ABSENCE claim a
+    // wrong locator satisfies it trivially: "the error message is gone" is true of a selector that
+    // never matched anything in the first place. Negation makes a presence check weaker, not stronger.
     if (PredicateKind.NOT === predicate.kind)
-        return walk(predicate.predicate);
+        return walk(predicate.predicate, true);
     // Leaf: classify against the single source of truth in core. Kinds that are neither consequence
     // nor presence (route/console/settled/animation) correctly return false for both.
     return {
         consequence: isConsequenceKind(predicate.kind),
-        presence: isPresenceKind(predicate.kind),
+        presence: isPresenceKind(predicate.kind) && (negated || !assertsElementContent(predicate)),
     };
 }
+/**
+ * An element predicate that checks the element's CONTENT, not merely that it is there.
+ *
+ * The presence nudge exists because "a locator healed to the wrong element, or a stale render, can
+ * satisfy this while the feature is broken". That is exactly true of `{ element, role, name }` and
+ * exactly false of `{ element, role, name, value: "274.58" }`: a wrong element now has to carry the
+ * same value to pass, which is the thing the nudge is warning cannot be relied on.
+ *
+ * Kept as a nudge-level distinction rather than a new honesty grade. The grade still reads
+ * `presence`, which UNDERSTATES what was proved, and understating is the safe direction for a field
+ * whose whole job is to qualify a green. Telling an agent that a value check "only checks presence"
+ * is the direction that costs something: it argues for replacing an assertion that is already sound.
+ */
+function assertsElementContent(predicate) {
+    if (predicate.kind !== PredicateKind.ELEMENT)
+        return false;
+    return predicate.query?.value !== undefined || predicate.query?.text !== undefined;
+}
 /**
  * True when the predicate asserts ONLY element/text presence with no signal/net consequence anywhere
  * — the weak pattern worth nudging. A predicate that mixes in a consequence, or that checks something

package/dist/tools/assert-verdict.js

@@ -1,9 +1,12 @@
+import { CaptureLoss } from '@reticlehq/core';
 import { findContradictions } from '../events/contradictions.js';
 import { blindSpotsFromState, buildCoverageStatement, Coverage, impeachesCapture, transportGapNote, } 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';
 import { decideVerified } from '../honesty/verified.js';
+import { describeWaitTarget } from '../honesty/unsettled.js';
+import { inFlightRequestLabels } from './settle-in-flight.js';
 import { gradeOfPredicate } from './assert-grade.js';
 /**
  * The honesty verdict for a plain `reticle_assert`.
@@ -48,7 +51,16 @@ observationLost) {
     // measured live, `observe` over a wide window reported `unit-mismatch` while `assert` on the same
     // session reported none. Attribution is unchanged: findings still come only from windowEvents.
     const prior = since > 0 ? (await session.queryEvents({ since: 0 })).filter((e) => e.t < since) : [];
-    const contradictions = findContradictions(windowEvents, { prior });
+    // The last act, when it falls inside the window being judged. Without it `duplicate-request` counted
+    // `method + url` across whatever window the caller asked for, so two legitimate separate saves to one
+    // endpoint were reported as a double submit — the instrument accusing the app of something nobody
+    // could show it did. An assert taken over a window that predates the act attributes nothing, and the
+    // rule then stays quiet.
+    const actCursor = session.lastAct.cursor();
+    const contradictions = findContradictions(windowEvents, {
+        prior,
+        ...(actCursor !== undefined && actCursor >= since ? { actionSince: actCursor } : {}),
+    });
     // Only a spot that IMPEACHES the capture downgrades a verdict. A structural boundary (virtualized
     // rows, a cross-origin frame) is reported as coverage and must not impugn what WAS observed.
     const impeaching = buildCoverageStatement(spots.filter((sp) => impeachesCapture(sp.kind)));
@@ -68,10 +80,22 @@ observationLost) {
             attribution: 'window',
             coveragePartial: Coverage.PARTIAL === statement.coverage,
             ...(0 === impeachingNotes.length ? {} : { blindSpots: impeachingNotes }),
+            // Which loss, as an enum, beside the prose. `assert` observes an already-open window and never
+            // consults the ring buffer's health, so `buffer_loss` is not one of its answers.
+            losses: [
+                ...(gap === undefined ? [] : [CaptureLoss.TRANSPORT_GAP]),
+                ...(impeaching.note === undefined ? [] : [CaptureLoss.BLIND_SPOT]),
+            ],
         }),
         contradictions,
         ...(outcomePending ? { outcomePending } : {}),
         ...(outcomeUnread ? { outcomeUnread } : {}),
+        // Same detail the act path supplies: this route reaches UNSETTLED through an absence-derived
+        // contradiction, and "the window closed before the app finished" is no more actionable here.
+        unsettled: {
+            waitedFor: describeWaitTarget(predicate),
+            stillInFlight: inFlightRequestLabels(windowEvents),
+        },
     });
     return { decision: decision, contradictions, coverage };
 }

package/dist/tools/contract-tools.js

@@ -38,6 +38,10 @@ export const CONTRACT_TOOLS = [
     {
         name: ReticleTool.CAPABILITIES,
         description: 'The app-advertised testable surface (reticle.describe): testids, signals, stores, and named flows. Call this first to learn what to assert on without reading source. Pass { fromDisk:true } to read the git-checked .reticle/contract.json instead of the live session (a fresh agent can learn the surface with no browser attached).',
+        // Every core tool carries one, so an agent reading the surface never has to guess the shape.
+        // `fromDisk` is the example deliberately: it is the call that works with nothing attached, which
+        // is the state a fresh agent is actually in when it first reads this list.
+        example: { [FROM_DISK_ARG]: true },
         inputSchema: { [FROM_DISK_ARG]: z.boolean().optional(), ...sessionIdShape },
         outputSchema: {
             testids: z.array(z.string()),

package/dist/tools/dynamic-tools.js

@@ -69,7 +69,7 @@ export function buildDynamicTools(allTools, profile) {
                 // `full` advertises all 46 tools DIRECTLY and carries no meta-tools at all, so
                 // reticle_run does not exist there. Saying otherwise sends the agent to a tool the
                 // profile does not have.
-                note: `The profile is read once at daemon startup — change ${TOOL_PROFILE_ENV} and restart the daemon, or it has no effect. Under this profile every unadvertised tool is reachable through reticle_run; under \`full\` there are no meta-tools because every tool is advertised directly.`,
+                note: `The profile is read once at daemon startup: change ${TOOL_PROFILE_ENV} and restart the daemon, or it has no effect. Under this profile every unadvertised tool is reachable through reticle_run; under \`full\` there are no meta-tools because every tool is advertised directly.`,
             },
         };
     const reticleTools = {

package/dist/tools/error-recovery.d.ts

@@ -8,6 +8,7 @@
  * on stable, human-authored substrings of the thrown messages (see session-manager.ts, the flow/
  * baseline stores). No clock, no IO — unit-testable in isolation.
  */
+import { RefusalReason } from '@reticlehq/core';
 /** The recovery hints, named so they are not free strings and can be asserted in tests. */
 export declare const RECOVERY: {
     readonly NO_SESSION: string;
@@ -40,6 +41,15 @@ export declare const RECOVERY: {
  * saying a server is running and the recovery saying to go start one.
  */
 export declare function recoveryFor(message: string): string | undefined;
+/**
+ * WHY a tool refused, as one of the six buckets in core's `RefusalReason`.
+ *
+ * Reads the SAME rules `buildErrorPayload` reads, in the same order, so the reason we report and the
+ * advice the agent got can never describe different things. Anything unrecognised is `other`, which
+ * is the bucket that says the classifier has a blind spot — and a growing `other` is a finding about
+ * this table rather than about anybody's app.
+ */
+export declare function refusalReasonFor(rawMessage: string): RefusalReason;
 /**
  * A serialized zod issue array, rendered as a sentence. Anything else is returned untouched.
  *