@reticlehq/server 2.7.0 → 2.8.0

package/dist/telemetry/install-source.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Which published route brought an install in.
+ *
+ * Four install routes ship at once and none of them could be told apart, so every question about
+ * where distribution effort is working had no data behind it at all.
+ *
+ * ONE mechanism: an environment variable a channel sets on itself. Everything else that looked like
+ * a signal turned out not to be one — see `InstallSource` in core for why `npm_config_user_agent`,
+ * a `.claude-plugin/` directory and an installed skill folder all fail to separate these routes.
+ *
+ * WHICH CHANNELS ARE GENUINELY DETECTABLE TODAY, so nobody later reads a small `unknown` as success:
+ *  - `plugin` — real. The Claude Code plugin registers the MCP server itself and can set the marker
+ *    in that server's `env`, so it is carried by the process without anybody typing anything.
+ *  - `skill_file` / `npx_skill` / `docs_site` / `readme` — real ONLY where that channel's own copy
+ *    of the install command carries the marker. Each is a separately published artifact, so a copy
+ *    that has not been updated is indistinguishable from no channel at all.
+ *  - `cli_direct` — NOT detectable. Nobody types a marker to say they typed a command. It exists so
+ *    a wrapper can declare it, and until something does, a direct install reports `unknown`.
+ *
+ * `unknown` is therefore expected to be the largest bucket for as long as the marker is spreading,
+ * and shrinking it is a distribution job, never a classifier job. A guessed attribution is worse
+ * than none: it is the number distribution decisions get steered on, and a guess and a measurement
+ * are indistinguishable once they are in the same column.
+ */
+import { InstallSource } from '@reticlehq/core';
+/** The one marker. Set by a channel on the process that runs the install. */
+export declare const INSTALL_SOURCE_ENV = "RETICLE_INSTALL_SOURCE";
+/**
+ * The declared install source, or `unknown`.
+ *
+ * Narrowed against the closed list rather than echoed: an echo would forward whatever somebody
+ * exported — a path, a URL, a campaign string — straight onto the wire, which is the rule this
+ * whole contract is built on. Trimmed and lowercased first, because the marker travels through
+ * shell snippets and copy-paste, and `Skill_File` is the same channel as `skill_file`.
+ */
+export declare function resolveInstallSource(env?: NodeJS.ProcessEnv): InstallSource;

package/dist/telemetry/install-source.js

@@ -0,0 +1,40 @@
+/**
+ * Which published route brought an install in.
+ *
+ * Four install routes ship at once and none of them could be told apart, so every question about
+ * where distribution effort is working had no data behind it at all.
+ *
+ * ONE mechanism: an environment variable a channel sets on itself. Everything else that looked like
+ * a signal turned out not to be one — see `InstallSource` in core for why `npm_config_user_agent`,
+ * a `.claude-plugin/` directory and an installed skill folder all fail to separate these routes.
+ *
+ * WHICH CHANNELS ARE GENUINELY DETECTABLE TODAY, so nobody later reads a small `unknown` as success:
+ *  - `plugin` — real. The Claude Code plugin registers the MCP server itself and can set the marker
+ *    in that server's `env`, so it is carried by the process without anybody typing anything.
+ *  - `skill_file` / `npx_skill` / `docs_site` / `readme` — real ONLY where that channel's own copy
+ *    of the install command carries the marker. Each is a separately published artifact, so a copy
+ *    that has not been updated is indistinguishable from no channel at all.
+ *  - `cli_direct` — NOT detectable. Nobody types a marker to say they typed a command. It exists so
+ *    a wrapper can declare it, and until something does, a direct install reports `unknown`.
+ *
+ * `unknown` is therefore expected to be the largest bucket for as long as the marker is spreading,
+ * and shrinking it is a distribution job, never a classifier job. A guessed attribution is worse
+ * than none: it is the number distribution decisions get steered on, and a guess and a measurement
+ * are indistinguishable once they are in the same column.
+ */
+import { InstallSource } from '@reticlehq/core';
+/** The one marker. Set by a channel on the process that runs the install. */
+export const INSTALL_SOURCE_ENV = 'RETICLE_INSTALL_SOURCE';
+const KNOWN = new Set(Object.values(InstallSource));
+/**
+ * The declared install source, or `unknown`.
+ *
+ * Narrowed against the closed list rather than echoed: an echo would forward whatever somebody
+ * exported — a path, a URL, a campaign string — straight onto the wire, which is the rule this
+ * whole contract is built on. Trimmed and lowercased first, because the marker travels through
+ * shell snippets and copy-paste, and `Skill_File` is the same channel as `skill_file`.
+ */
+export function resolveInstallSource(env = process.env) {
+    const declared = (env[INSTALL_SOURCE_ENV] ?? '').trim().toLowerCase();
+    return KNOWN.has(declared) ? declared : InstallSource.UNKNOWN;
+}

package/dist/telemetry/run-telemetry.js

@@ -10,7 +10,7 @@
  * finished, already-classified verdict, so this cannot double-count and does not need to understand
  * how a replay works.
  */
-import { BugSource, RunFlowStatus, TelemetryActor, TelemetryEventKind, VerdictStatus, } from '@reticlehq/core';
+import { BugAttribution, BugSource, RunFlowStatus, TelemetryActor, TelemetryEventKind, VerdictStatus, } from '@reticlehq/core';
 import { getSessionMetrics } from './session-metrics.js';
 import { getTelemetry } from './telemetry.js';
 /** The tool name reported for this path, so CI runs are distinguishable from agent-driven ones. */
@@ -52,6 +52,9 @@ export function reportRunTelemetry(run) {
                     falseGreen: false,
                     tool: VERIFY_SURFACE,
                     repeat: !first,
+                    // A regression SOMEWHERE, and the row does not say where — the app changed, or a selector
+                    // strategy of ours did. `app` needs positive evidence; see bug-found.ts.
+                    attribution: BugAttribution.UNCLASSIFIED,
                 },
             });
         }

package/dist/telemetry/session-metrics.js

@@ -515,6 +515,11 @@ export class SessionMetrics {
                 : {}),
             ...(this.#surface === undefined ? {} : { surface: this.#surface }),
             ...(final ? { endReason: this.#endReason() } : {}),
+            // The headline metric, as a FIELD. Read off the lifetime counter, because every other
+            // verification number in this payload is windowed and a reader who summed the wrong one got a
+            // different question's answer. `false` is sent, not omitted: a session that drove an app and
+            // never asked whether it worked is the whole finding.
+            ...(final ? { endedWithVerdict: this.#lifetimeVerifications > 0 } : {}),
             ...(this.#feedbackPrompted > 0 ? { feedbackPrompted: this.#feedbackPrompted } : {}),
             ...(this.#errorClasses.size > 0
                 ? { errorClasses: Object.fromEntries(this.#errorClasses) }

package/dist/telemetry/telemetry.d.ts

@@ -1,4 +1,4 @@
-import { TelemetryEventKind, ProjectIdSource, type Crash, type Feedback, type Identity, type BugFound, type InitOutcome, type McpConnection, type McpOutage, type AppInstrumentation, type ProjectProfile, type SessionSummary, type TelemetryActor, type Verification, type VersionChange } from '@reticlehq/core';
+import { TelemetryEventKind, ProjectIdSource, type Crash, type Feedback, type Identity, type BugFound, type InitOutcome, type InstallSource, type McpConnection, type McpOutage, type ToolRefusal, type AppInstrumentation, type ProjectProfile, type SessionSummary, type TelemetryActor, type Verification, type VersionChange } from '@reticlehq/core';
 /**
  * Feedback gets its own, much larger budget — and a retry.
  *
@@ -72,10 +72,14 @@ export interface TelemetryExtra {
     init?: InitOutcome;
     /** `bug_found`: one defect Reticle found in the app under test. */
     bug?: BugFound;
+    /** `tool_refused`: a call Reticle could not serve, and why. */
+    refusal?: ToolRefusal;
     /** `mcp_connection_lost`: the agent lost its tools — which stage, and why. */
     outage?: McpOutage;
     /** `app_instrumented`: an app carrying the SDK reached this daemon for the first time. */
     instrumentation?: AppInstrumentation;
+    /** `reticle_installed` / `init_completed`: which published route brought this install in. */
+    installSource?: InstallSource;
 }
 export interface Telemetry {
     /**

package/dist/telemetry/telemetry.js

@@ -71,6 +71,7 @@ const DETACHED_SEND_SCRIPT = "fetch(process.argv[1],{method:'POST',headers:{'con
 /** Env var names — mirror cloud-sync's `RETICLE_*` convention. */
 import { isReticleSourceCheckout } from './dev-repo.js';
 import { gitFacts } from './git-facts.js';
+import { currentAutomationHint } from './automation-hint.js';
 const Env = {
     DISABLE: 'RETICLE_TELEMETRY', // "0" / "false" / "off" → disabled
     DO_NOT_TRACK: 'DO_NOT_TRACK', // the cross-tool opt-out convention (any truthy value)
@@ -200,7 +201,7 @@ export const describeTelemetry = (env = process.env, dir = RETICLE_DIR, cwd = pr
     if (isReticleSourceCheckout(cwd)) {
         return {
             enabled: false,
-            reason: 'this is a Reticle source checkout — developing it is not using it',
+            reason: 'this is a Reticle source checkout; developing it is not using it',
             policyUrl: POLICY_URL,
         };
     }
@@ -259,6 +260,9 @@ export const createTelemetry = (opts) => {
     const doFetch = opts.fetchImpl ?? fetch;
     const url = `${(env[Env.URL] ?? DEFAULT_URL).replace(/\/+$/, '')}${TELEMETRY_PATH}`;
     const ci = env[Env.CI] !== undefined && env[Env.CI] !== '';
+    // Read once per process, next to `ci` and never instead of it: this is a second angle on the same
+    // question, and the rule that it can never filter a row lives in automation-hint.ts.
+    const automation = currentAutomationHint(env);
     const os = platform();
     // Negated so it reads the way people say it: UTC+2 is +120, not -120.
     const tzOffsetMin = -new Date().getTimezoneOffset();
@@ -300,6 +304,9 @@ export const createTelemetry = (opts) => {
             ts: now(),
             version: opts.version,
             ci,
+            // A SCALAR, so it needs the event build and the wire schema and no `blocks` entry — the same
+            // three-place trap `outage` fell into, and `installSource` documents below.
+            ...(automation !== undefined ? { automation } : {}),
             os,
             tzOffsetMin,
             projectIdSource,
@@ -316,15 +323,20 @@ export const createTelemetry = (opts) => {
             ...(extra?.connection !== undefined ? { connection: extra.connection } : {}),
             ...(extra?.init !== undefined ? { init: extra.init } : {}),
             ...(extra?.bug !== undefined ? { bug: extra.bug } : {}),
+            ...(extra?.refusal !== undefined ? { refusal: extra.refusal } : {}),
             ...(extra?.outage !== undefined ? { outage: extra.outage } : {}),
             ...(extra?.instrumentation !== undefined ? { instrumentation: extra.instrumentation } : {}),
+            // A SCALAR, so it needs the event build and the wire schema but no entry in `blocks` below —
+            // there is nothing to flatten. It still needs both of those, which is the trap `outage` fell
+            // into: a field declared on TelemetryExtra and missing from either one is dropped in silence.
+            ...(extra?.installSource !== undefined ? { installSource: extra.installSource } : {}),
         };
         // Map the core contract onto PostHog's capture shape: id/name/time move up, the rest are properties.
         // The feedback body is FLATTENED into `feedback_*` properties rather than sent as a nested object:
         // PostHog filters and breakdowns operate on top-level properties, so a nested `feedback.stack`
         // would be invisible to the exact "which stacks report the most bugs" question this exists to
         // answer. One prefix keeps them grouped in the UI without a nested path.
-        const { anonymousId: distinctId, event: name, ts, sessionId: eventSessionId, feedback, session, project, verification, versionChange, crash, identity, connection, init, bug, outage, instrumentation, ...rest } = event;
+        const { anonymousId: distinctId, event: name, ts, sessionId: eventSessionId, feedback, session, project, verification, versionChange, crash, identity, connection, init, bug, refusal, outage, instrumentation, ...rest } = event;
         // `$session_id` is PostHog's OWN session property, so sending ours under that name lights up
         // its built-in session views and funnels for free rather than requiring custom HogQL everywhere.
         // `sessionId` rides only on events that happened inside a daemon run. A one-shot CLI command
@@ -352,6 +364,7 @@ export const createTelemetry = (opts) => {
             connection,
             init,
             bug,
+            refusal,
             outage,
             instrumentation,
         };

package/dist/telemetry/tool-refused.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Reporting the calls Reticle could not serve.
+ *
+ * The refusal path is the largest thing this product does and the least measured one. It computes a
+ * precise diagnosis — which of three no-session situations this is, that a ref went stale, that a
+ * predicate did not parse — hands it to the agent as prose, and throws it away. So a user who
+ * attaches an agent, hits a wall on the first call and never comes back emits nothing at all, and
+ * the whole cohort is visible only as the gap between two other numbers. See issue #172.
+ *
+ * Emitted from `runTool`, which is the one place both dispatch paths cross, so a tool added later is
+ * covered without anybody remembering to cover it.
+ */
+import { type RefusalReason } from '@reticlehq/core';
+/** A call that was served. Breaks the retry chain: what follows it is not a retry of anything. */
+export declare function noteToolServed(): void;
+/** One refused call, reported with its cause and whether it was itself a retry. */
+export declare function reportToolRefused(tool: string, reason: RefusalReason): void;
+/** Tests only — the counters are process-lifetime, so each case has to start from zero. */
+export declare function resetToolRefusals(): void;

package/dist/telemetry/tool-refused.js

@@ -0,0 +1,55 @@
+/**
+ * Reporting the calls Reticle could not serve.
+ *
+ * The refusal path is the largest thing this product does and the least measured one. It computes a
+ * precise diagnosis — which of three no-session situations this is, that a ref went stale, that a
+ * predicate did not parse — hands it to the agent as prose, and throws it away. So a user who
+ * attaches an agent, hits a wall on the first call and never comes back emits nothing at all, and
+ * the whole cohort is visible only as the gap between two other numbers. See issue #172.
+ *
+ * Emitted from `runTool`, which is the one place both dispatch paths cross, so a tool added later is
+ * covered without anybody remembering to cover it.
+ */
+import { TelemetryActor, TelemetryEventKind } from '@reticlehq/core';
+import { getTelemetry } from './telemetry.js';
+/**
+ * Refusal events one daemon run will send.
+ *
+ * Volume is part of this taxonomy's design — the per-tool-call event was removed for exactly this
+ * reason — and a stuck agent retrying one failing call is the shape most likely to produce hundreds.
+ * The cap means the bill cannot scale with the pathology while the SHAPE of it still arrives: the
+ * first fifty carry the tool, the cause and the retry flag, and `consecutiveRepeats` on the session
+ * summary already reports how long the loop ran.
+ */
+const MAX_REFUSALS_PER_SESSION = 50;
+let sent = 0;
+/**
+ * The tool whose call refused immediately before this one, if the last call refused at all.
+ *
+ * This is what `retried` is computed from, and it is why the event is sent at the moment of the
+ * refusal rather than held back until the next call reveals whether one came. Holding it back would
+ * lose the event entirely for an agent that gives up — which is precisely the agent this exists to
+ * describe — so the flag lands on the RETRY instead of on the first refusal.
+ */
+let lastRefusedTool;
+/** A call that was served. Breaks the retry chain: what follows it is not a retry of anything. */
+export function noteToolServed() {
+    lastRefusedTool = undefined;
+}
+/** One refused call, reported with its cause and whether it was itself a retry. */
+export function reportToolRefused(tool, reason) {
+    const retried = lastRefusedTool === tool;
+    lastRefusedTool = tool;
+    if (sent >= MAX_REFUSALS_PER_SESSION)
+        return;
+    sent += 1;
+    void getTelemetry().emit(TelemetryEventKind.TOOL_REFUSED, {
+        actor: TelemetryActor.AGENT,
+        refusal: { tool, reason, retried },
+    });
+}
+/** Tests only — the counters are process-lifetime, so each case has to start from zero. */
+export function resetToolRefusals() {
+    sent = 0;
+    lastRefusedTool = undefined;
+}

package/dist/telemetry/verification-of.js

@@ -53,6 +53,38 @@ 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.
  *
@@ -73,13 +105,7 @@ 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);
@@ -88,6 +114,19 @@ export function verificationOf(toolName, result, durationMs, brand) {
         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

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

@@ -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';
@@ -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.
@@ -380,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'];
@@ -467,9 +500,13 @@ export const ACT_TOOLS = [
                 // 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;
@@ -492,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

@@ -5,6 +5,8 @@ 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`.
@@ -49,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)));
@@ -79,6 +90,12 @@ observationLost) {
         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()),