@reticlehq/server 2.8.0 → 2.10.0

package/dist/events/stale-response.js

@@ -91,6 +91,49 @@ function flights(events) {
  */
 const MAX_FLIGHTS_PER_PATH = 60;
 /** The one contradiction, or none. Reported once per window — a race is a fact about the window. */
+/**
+ * How long after a superseded response lands we look for the app reacting to it.
+ *
+ * A handler runs on the microtask that resolves the fetch; the render follows within a frame or two.
+ * Beyond this the connection between the response and any change is speculation.
+ */
+const APPLY_WINDOW_MS = 500;
+/**
+ * How far BEFORE the completion stamp a reaction still counts as reacting to it.
+ *
+ * Not a fudge factor — a correction for which of the two is stamped first. `NET_REQUEST` is emitted
+ * when the observer's wrapper sees the fetch settle, and the app's own handler runs on the same
+ * microtask; in practice the app's state write, signal and DOM text land at or a millisecond BEFORE
+ * the completion event that caused them.
+ *
+ * So a strictly-forward window could not see the application at all, and the rule could never fire on
+ * real traffic however plainly the app misbehaved. Sixteen passing unit tests did not catch that,
+ * because synthetic events are written with the reaction placed after the cause.
+ */
+const APPLY_SLACK_MS = 100;
+/**
+ * Did the app REACT to this response — did anything user-visible move after it landed?
+ *
+ * The question the rule could not previously ask, and the difference between a defect and a
+ * correctly-handled race. An app that guards against superseded responses still RACES: two requests
+ * overlap and settle out of order exactly as before. What it does not do is act on the loser.
+ *
+ * Without this check the rule fires identically on both, which is worse than not having it: a
+ * detector that accuses correct code teaches people to ignore it, and it takes the true positives
+ * down with it.
+ */
+function appliedAfter(events, settledAt) {
+    return events.some((event) => {
+        if (event.t < settledAt - APPLY_SLACK_MS || event.t > settledAt + APPLY_WINDOW_MS)
+            return false;
+        return (event.type === EventType.STATE_CHANGE ||
+            event.type === EventType.SIGNAL ||
+            event.type === EventType.DOM_TEXT ||
+            event.type === EventType.DOM_ADDED ||
+            event.type === EventType.DOM_REMOVED ||
+            event.type === EventType.DOM_ATTR);
+    });
+}
 export function findStaleResponses(events) {
     // Grouped by path first: two reads of DIFFERENT endpoints can never race, and comparing them was
     // the bulk of the work on any real page, which talks to many endpoints at once.
@@ -105,13 +148,13 @@ export function findStaleResponses(events) {
     }
     for (const group of byPath.values()) {
         const reads = group.slice(-MAX_FLIGHTS_PER_PATH);
-        const found = raceIn(reads);
+        const found = raceIn(reads, events);
         if (found !== undefined)
             return [found];
     }
     return [];
 }
-function raceIn(reads) {
+function raceIn(reads, events) {
     for (const first of reads) {
         for (const second of reads) {
             if (first.id === second.id)
@@ -127,6 +170,10 @@ function raceIn(reads) {
             // Parallel pagination is not a race — see differsOnlyByEnumeration.
             if (differsOnlyByEnumeration(queryOf(first.url), queryOf(second.url)))
                 continue;
+            // The race happened. Whether it MATTERS is whether the app acted on the loser — an app that
+            // drops superseded responses races just as visibly and is not broken.
+            if (!appliedAfter(events, first.settledAt))
+                continue;
             return {
                 kind: ContradictionKind.STALE_RESPONSE_APPLIED,
                 claim: `both reads of ${pathOf(first.url)} returned successfully and the page settled`,

package/dist/events/unit-mismatch.d.ts

@@ -1,5 +1,5 @@
 import { type ReticleEvent } from '@reticlehq/core';
-import type { Contradiction } from './contradictions.js';
+import type { OwnContradiction } from './contradictions.js';
 /**
  * @param prior events from BEFORE the window, used only to learn what the API has stated.
  *
@@ -13,4 +13,4 @@ import type { Contradiction } from './contradictions.js';
  * every other rule blame this action for events it did not cause, and would re-report every earlier
  * mistake on every assert.
  */
-export declare function findUnitMismatches(events: readonly ReticleEvent[], prior?: readonly ReticleEvent[]): Contradiction[];
+export declare function findUnitMismatches(events: readonly ReticleEvent[], prior?: readonly ReticleEvent[]): OwnContradiction[];

package/dist/flows/annotate-tools.js

@@ -118,6 +118,9 @@ export const ANNOTATE_TOOLS = [
             recovery: z.string().optional(),
             target: z.string().optional(),
             compiled: z.string().optional(),
+            // Set when the compiled annotation would overstate what a replay can check — e.g. a
+            // success-state that flow_save will grade assertion-free (#395).
+            note: z.string().optional(),
             code: z.string().optional(),
         },
         handler: (deps, args) => {

package/dist/flows/annotate.js

@@ -1,4 +1,4 @@
-import { AnnotationErrorCode, AnnotationKind, AnnotationTarget, COMPILED_PREDICATE_PREFIX, } from '@reticlehq/core';
+import { AnnotationErrorCode, AnnotationKind, AnnotationTarget, COMPILED_PREDICATE_PREFIX, flowExpectHasConsequence, flowExpectIsPresenceOnly, } from '@reticlehq/core';
 /**
  * The PURE compiler at the heart of the annotation facet. A structured annotation +
  * the current captured-step count → an AnnotateOutcome (a result envelope + the patch to apply to
@@ -96,11 +96,25 @@ function stepPatch(a, stepCount, stepExpect) {
         patch: { stepIndex: stepCount - 1, stepExpect },
     };
 }
+// A success end-condition that is not an observable CONSEQUENCE (signal / net / state) cannot lift
+// the flow above the grade flow_save will give it. Saying "will succeed when ..." without that
+// caveat is the #395 contradiction: annotate promises a check that flow_save then grades
+// assertion-free, so a flow that only checks the console replays green through any regression. Name
+// the grade here, using the same consequence/presence classification every grader shares.
+const SUCCESS_ASSERTION_FREE_NOTE = 'This success-state is not an observable consequence, so flow_save will grade the flow assertion-free — it passes even when the feature is broken. Use a signal / net / state success-state to give the flow something that can fail.';
+const SUCCESS_PRESENCE_ONLY_NOTE = 'This success-state only checks element presence, so flow_save will grade the flow presence-only — a locator healed to the wrong element still passes it. Use a signal / net / state success-state to assert an observable consequence.';
 function flowSuccess(a, success) {
-    return {
-        result: { ok: true, target: AnnotationTarget.FLOW, compiled: describeCompiled(a) },
-        patch: { success },
+    const result = {
+        ok: true,
+        target: AnnotationTarget.FLOW,
+        compiled: describeCompiled(a),
     };
+    if (!flowExpectHasConsequence(success)) {
+        result.note = flowExpectIsPresenceOnly(success)
+            ? SUCCESS_PRESENCE_ONLY_NOTE
+            : SUCCESS_ASSERTION_FREE_NOTE;
+    }
+    return { result, patch: { success } };
 }
 /**
  * Human-readable confirmation text for the recorder strip / tool result,

package/dist/flows/coverage.d.ts

@@ -9,11 +9,18 @@ interface DeclaredSurface {
     signals: readonly string[];
     flows: readonly string[];
 }
-interface CoverageDimension {
+export interface CoverageDimension {
     total: number;
     covered: number;
-    /** Percent covered, rounded; 100 when nothing is declared (vacuously complete). */
-    pct: number;
+    /**
+     * Percent covered, rounded. PRESENT ONLY WHEN IT WAS MEASURED — absent when nothing is declared,
+     * same rule as the honesty layer's `{ pct?: number; partial: boolean }`.
+     *
+     * This used to report 100 for an empty surface ("vacuously complete"), which made
+     * `covered: 0, total: 0, pct: 100` — a contradiction the caller had to notice unaided, in output an
+     * agent reads to decide whether its change is covered.
+     */
+    pct?: number;
     /** Declared-but-never-exercised members — what "everything" is silently missing. */
     uncovered: string[];
 }
@@ -21,8 +28,34 @@ export interface Coverage {
     testids: CoverageDimension;
     signals: CoverageDimension;
     flows: CoverageDimension;
-    /** Overall percent across all three dimensions combined. */
-    overallPct: number;
+    /** Overall percent across all three dimensions combined; absent when nothing is declared. */
+    overallPct?: number;
 }
+/** The gate's outcome when the project has recorded no flows at all — not a pass, and not a failure. */
+export declare const NO_FLOWS = "no_flows";
+/**
+ * What to do about it, since the empty state is otherwise indistinguishable from success.
+ *
+ * Names the TOOLS, not a `reticle record` CLI verb: this CLI does not dispatch one, and a suggestion
+ * that errors is a second dead end on top of the first (see suggested-commands-exist.test.ts). Same
+ * wording as the empty-suite verdict, which is the same situation reached from `reticle verify`.
+ */
+export declare const NO_FLOWS_NOTE = "no flows recorded \u2014 nothing was checked. Record one with reticle_record { action: \"start\" }, then reticle_flow_save.";
+/** The gate's flow-coverage line. `pct` and `outcome` are mutually exclusive by construction. */
+export interface FlowCoverageReport {
+    covered: number;
+    total: number;
+    pct?: number;
+    outcome?: typeof NO_FLOWS;
+    note?: string;
+}
+/**
+ * Report flow coverage so that an EMPTY suite cannot be read as a passing one.
+ *
+ * Same rule `buildSuiteVerdict` already applies to `reticle verify`, where zero flows reports
+ * `unverifiable` rather than "all 0 flows pass": a green that cannot go red is not a pass. Callers
+ * must treat a present `outcome` as not-passing.
+ */
+export declare function flowCoverageReport(flows: CoverageDimension): FlowCoverageReport;
 export declare function computeCoverage(declared: DeclaredSurface, exercised: DeclaredSurface): Coverage;
 export {};

package/dist/flows/coverage.js

@@ -4,11 +4,36 @@
  * (contract testids/signals/flows) actually touched by passing verification, so "everything" is honest
  * about what everything means. Pure set math; the deviation report + gate carry the number.
  */
+/** The gate's outcome when the project has recorded no flows at all — not a pass, and not a failure. */
+export const NO_FLOWS = 'no_flows';
+/**
+ * What to do about it, since the empty state is otherwise indistinguishable from success.
+ *
+ * Names the TOOLS, not a `reticle record` CLI verb: this CLI does not dispatch one, and a suggestion
+ * that errors is a second dead end on top of the first (see suggested-commands-exist.test.ts). Same
+ * wording as the empty-suite verdict, which is the same situation reached from `reticle verify`.
+ */
+export const NO_FLOWS_NOTE = 'no flows recorded — nothing was checked. Record one with reticle_record { action: "start" }, then reticle_flow_save.';
+/**
+ * Report flow coverage so that an EMPTY suite cannot be read as a passing one.
+ *
+ * Same rule `buildSuiteVerdict` already applies to `reticle verify`, where zero flows reports
+ * `unverifiable` rather than "all 0 flows pass": a green that cannot go red is not a pass. Callers
+ * must treat a present `outcome` as not-passing.
+ */
+export function flowCoverageReport(flows) {
+    const { covered, total } = flows;
+    if (0 === total)
+        return { covered, total, outcome: NO_FLOWS, note: NO_FLOWS_NOTE };
+    return { covered, total, ...(flows.pct === undefined ? {} : { pct: flows.pct }) };
+}
 function dimension(declared, exercised) {
     const uncovered = declared.filter((d) => !exercised.has(d));
     const covered = declared.length - uncovered.length;
-    const pct = 0 === declared.length ? 100 : Math.round((covered / declared.length) * 100);
-    return { total: declared.length, covered, pct, uncovered };
+    const base = { total: declared.length, covered, uncovered };
+    if (0 === declared.length)
+        return base;
+    return { ...base, pct: Math.round((covered / declared.length) * 100) };
 }
 export function computeCoverage(declared, exercised) {
     const testids = dimension(declared.testids, new Set(exercised.testids));
@@ -16,6 +41,7 @@ export function computeCoverage(declared, exercised) {
     const flows = dimension(declared.flows, new Set(exercised.flows));
     const total = testids.total + signals.total + flows.total;
     const covered = testids.covered + signals.covered + flows.covered;
-    const overallPct = 0 === total ? 100 : Math.round((covered / total) * 100);
-    return { testids, signals, flows, overallPct };
+    if (0 === total)
+        return { testids, signals, flows };
+    return { testids, signals, flows, overallPct: Math.round((covered / total) * 100) };
 }

package/dist/flows/decision.d.ts

@@ -1,5 +1,20 @@
 import { type FlowFile, type FlowReplayResult, type ReplayDecision, type SuiteVerdict } from '@reticlehq/core';
 export declare function buildDecision(result: FlowReplayResult, flow?: FlowFile): ReplayDecision;
+/**
+ * Aggregate per-flow replays into one suite verdict — the autonomous loop's consolidated answer
+ * after a build: did anything break, and what's the prioritized fix list. Pure: pass the already
+ * decision-annotated replay results + their flows. Passing flows are counted; only failures carry
+ * detail (token-cheap), each with the actionable decision so the agent fixes without re-querying.
+ */
+/**
+ * Why a green replay still verified nothing, or undefined when it genuinely did.
+ *
+ * A flow with no steps, or one that asserts no observable consequence, replays green no matter what
+ * the app does — the grader already knows this at save time and says so. Counting it as `passed`
+ * turned that warning into "all 1 flow pass", which is a false green in the exact feature sold as
+ * the regression suite. Classified only when the flow file is available; never guessed.
+ */
+export declare function unverifiableReason(flow: FlowFile | undefined): string | undefined;
 export declare function buildSuiteVerdict(runs: ReadonlyArray<{
     replay: FlowReplayResult;
     flow?: FlowFile;

package/dist/flows/decision.js

@@ -100,7 +100,7 @@ function suiteVerdictOf(status) {
  * turned that warning into "all 1 flow pass", which is a false green in the exact feature sold as
  * the regression suite. Classified only when the flow file is available; never guessed.
  */
-function unverifiableReason(flow) {
+export function unverifiableReason(flow) {
     if (flow === undefined)
         return undefined;
     if (0 === flow.steps.length) {

package/dist/flows/flow-replay-run.js

@@ -2,7 +2,7 @@ import { EventType, FLOW_SIGNAL_TIMEOUT_MS, FlowErrorCode, RecordedFlowSchema, R
 import { asString } from '../tools/tools-helpers.js';
 import { replayFlow } from './flow-replay.js';
 import { assertSuccess, dynamicTestids, successLabel, SUCCESS_STEP_TOOL } from './flow-success.js';
-import { buildDecision } from './decision.js';
+import { buildDecision, unverifiableReason } from './decision.js';
 import { waitForPredicate } from '../events/predicate.js';
 import { computeSegments } from '../journal/rollups.js';
 import { AssertionTiersStore } from './assertion-tiers-store.js';
@@ -174,6 +174,13 @@ export async function replayNamedFlow(deps, args) {
         return errored;
     }
     const result = { name, status, steps };
+    // A green that cannot go red is not a pass. `reticle_flow_verify` already refuses to count these,
+    // via this same function -- a single-flow caller saw a bare `ok` and had no way to learn the flow
+    // asserts nothing. Derived from the same helper on purpose: two copies of this judgement would
+    // drift, and the sibling tools would then disagree about the same flow.
+    const cannotFail = status === ReplayStatus.OK ? unverifiableReason(loaded.value) : undefined;
+    if (cannotFail !== undefined)
+        result.unverifiable = { reason: cannotFail };
     if (status !== ReplayStatus.OK)
         result.decision = buildDecision(result, loaded.value);
     applyStartPathHint(result, startPathHint);

package/dist/flows/flow-tools.js

@@ -255,7 +255,9 @@ export const FLOW_TOOLS = [
             'stale ref. On an anchor MISS returns legible DRIFT { step, anchor, drift:{ reasonKind, reason, ' +
             'nearest } } (the closest surviving testid) and stops — the "whose fault is it" contract. ' +
             'Returns { name, status: ok|drift|error, steps:[...] }; missing/malformed files and action ' +
-            'failures are status:error with a structured code (distinct from contract-changed drift).',
+            'failures are status:error with a structured code (distinct from contract-changed drift). ' +
+            'An ok replay of a flow that asserts no consequence also carries unverifiable:{reason} — it ' +
+            'would read ok even if the feature were broken, so do NOT treat that ok as proof.',
         inputSchema: {
             flow: z
                 .string()
@@ -285,6 +287,12 @@ export const FLOW_TOOLS = [
                 .optional()
                 .describe('Push-default deviation report over the replay segments: ranked deviations vs the learned envelope + a nominal count, or a fall-back note below 3 runs.'),
             error: z.object({ code: z.string(), message: z.string() }).optional(),
+            // Declared here or a validating profile strips it -- the same way `name` was stripped once.
+            // A field the handler sets and the schema omits arrives as nothing, silently.
+            unverifiable: z
+                .object({ reason: z.string() })
+                .optional()
+                .describe('Set on an ok replay that cannot fail: the flow asserts no observable consequence, so it passes even when the feature is broken. Same reason reticle_verify{action:"flows"} reports.'),
             decision: z
                 .object({
                 verdict: z.string(),

package/dist/flows/replay.js

@@ -247,6 +247,9 @@ export async function replayProgram(session, program, confirmDangerous = false)
                 session.beginAction(ReticleTool.REPLAY, { steps: liveSteps.length });
                 let r;
                 try {
+                    // DIVERGENCE: replay sends one batched ACT_SEQUENCE command to the browser;
+                    // live (tools/act-tools.ts) sends N individual ACT commands for per-step timeout +
+                    // progress. A bug in either is invisible from the other.
                     r = await session.command(ReticleCommand.ACT_SEQUENCE, { steps: liveSteps });
                 }
                 finally {

package/dist/flows/verify-change-tools.js

@@ -97,7 +97,7 @@ export const VERIFY_CHANGE_TOOLS = [
             const cursor = cursorBeforeReplay(deps, args);
             const verify = FLOW_TOOLS.find((tool) => tool.name === ReticleTool.FLOW_VERIFY);
             if (verify === undefined)
-                throw new Error('reticle_flow_verify is not registered');
+                throw new Error('the whole-suite replay tool is not registered');
             const suite = asRecord(await verify.handler(deps, {
                 names: affected,
                 ...(asNumber(args['parallel']) === undefined ? {} : { parallel: args['parallel'] }),

package/dist/honesty/accepted-write.d.ts

@@ -10,5 +10,8 @@ import { type ReticleEvent } from '@reticlehq/core';
  * optimistically rendered "dispatched", the page settled, every channel agreed — and the server
  * REVERTED it to `held` 1.2 s later. The verdict was not wrong about what it observed. It was early,
  * and nothing in the response said so except the status code nobody was reading.
+ *
+ * The DEV TOOLCHAIN's own traffic is excluded, on the same rule every other check applies: a verdict
+ * about the app must not be decided by a request the app did not make.
  */
 export declare function hasAcceptedWrite(events: readonly ReticleEvent[]): boolean;

package/dist/honesty/accepted-write.js

@@ -1,5 +1,5 @@
-import { EventType, HTTP_ACCEPTED } from '@reticlehq/core';
-import { asNumber } from '../tools/tools-helpers.js';
+import { EventType, HTTP_ACCEPTED, isDevToolingUrl } from '@reticlehq/core';
+import { asNumber, asString } from '../tools/tools-helpers.js';
 /**
  * Did a write in this window answer `202 Accepted`?
  *
@@ -11,7 +11,12 @@ import { asNumber } from '../tools/tools-helpers.js';
  * optimistically rendered "dispatched", the page settled, every channel agreed — and the server
  * REVERTED it to `held` 1.2 s later. The verdict was not wrong about what it observed. It was early,
  * and nothing in the response said so except the status code nobody was reading.
+ *
+ * The DEV TOOLCHAIN's own traffic is excluded, on the same rule every other check applies: a verdict
+ * about the app must not be decided by a request the app did not make.
  */
 export function hasAcceptedWrite(events) {
-    return events.some((e) => e.type === EventType.NET_REQUEST && asNumber(e.data['status']) === HTTP_ACCEPTED);
+    return events.some((e) => e.type === EventType.NET_REQUEST &&
+        asNumber(e.data['status']) === HTTP_ACCEPTED &&
+        !isDevToolingUrl(asString(e.data['url'])));
 }

package/dist/honesty/already-true.js

@@ -17,8 +17,23 @@
 import { PredicateKind } from '@reticlehq/core';
 export function readsDomState(predicate) {
     switch (predicate.kind) {
+        // ROUTE is here, and it did not used to be. It was purely event-based — satisfiable only by a
+        // navigation inside the act's window, and therefore unable to be answered by the past — so it
+        // sat with the floored kinds below.
+        //
+        // It gained a fallback to the CURRENT route for the case where the window holds no route change,
+        // which is what makes "did the session survive a reload?" answerable at all. Without a
+        // before-check that fallback is a guaranteed green: the app is already on /login, the click's
+        // handler is broken, nothing navigates, and an assertion that the action reached /login passes
+        // on the strength of it having been there all along. A bare `{ kind: 'route' }` becomes
+        // unconditionally true, because there is always a current route.
+        //
+        // One extra query on the act path buys `already_true`, reported as UNKNOWN with the reason
+        // rather than as a pass. The fallback removed a false red; this is what stops it becoming a
+        // false green, and that is the trade this codebase never makes.
         case PredicateKind.ELEMENT:
         case PredicateKind.TEXT:
+        case PredicateKind.ROUTE:
             return true;
         case PredicateKind.ALL_OF:
         case PredicateKind.ANY_OF:

package/dist/honesty/blind-spots.js

@@ -40,6 +40,10 @@ const LABEL = {
     // nothing here was missed, there was simply never a verdict to observe, and no amount of extra
     // instrumentation would produce one.
     [BlindSpotKind.VERDICTLESS_SEND]: (n) => `${String(n)} one-way IPC send${1 === n ? '' : 's'} dispatched with NO verdict — the renderer never learns whether the main process handled ${1 === n ? 'it' : 'them'}, so this cannot be confirmed from the page`,
+    // Not a tally — a fact about the app's wiring, phrased as what the EMPTY state channel means. An
+    // agent reading `stateDiffs: []` otherwise reads "the app changed no state", which is a claim
+    // nothing here can support. Names the one-line fix, because the reader is the one who can apply it.
+    [BlindSpotKind.UNWATCHED_STATE]: () => 'no subscribable store is registered, so NO state change is observed — an empty stateDiffs here means unwatched, not unchanged (register the store itself in your reticle-dev module: registerStore(name, store), not a getter)',
     [BlindSpotKind.WRAPPED_NETWORK]: () => 'fetch was already wrapped before Reticle, so recorded requests may differ from what was sent',
     // A fact about the app's wiring, not a tally. Says what the empty network view MEANS, because an
     // empty one here is indistinguishable from "this app made no backend calls" — and that reading is

package/dist/honesty/honesty.d.ts

@@ -33,6 +33,15 @@ interface HonestyInputs {
      * knows whether a blind-spot note came from the browser transport or from a boundary in the page.
      */
     losses?: readonly CaptureLoss[];
+    /**
+     * Did the page go quiet inside the action's window? Omitted when nothing measured it.
+     *
+     * Settlement stopped being a veto over a declared consequence that held (see `verified.ts`), and a
+     * fact that no longer decides the verdict must not therefore disappear: a page that never goes
+     * idle is worth knowing about, and a caller who cares can still gate on it. Reported here rather
+     * than beside `verified`, where the answer belongs to the rule and not to its inputs.
+     */
+    settled?: boolean;
 }
 export interface HonestyBlock {
     grade: HonestyGrade;
@@ -52,6 +61,8 @@ export interface HonestyBlock {
         issues: string[];
         losses?: CaptureLoss[];
     };
+    /** Whether the page went quiet in this window — present only when it was measured. */
+    settled?: boolean;
 }
 export declare function buildHonestyBlock(inputs: HonestyInputs): HonestyBlock;
 interface HonestyBar {

package/dist/honesty/honesty.js

@@ -46,6 +46,7 @@ export function buildHonestyBlock(inputs) {
             ? {}
             : { envelope: { samples, sufficient: samples >= MIN_ENVELOPE_SAMPLES } }),
         coverage: { ...(pct === undefined ? {} : { pct }), partial },
+        ...(inputs.settled === undefined ? {} : { settled: inputs.settled }),
         integrity: {
             clean: 0 === issues.length,
             issues,

package/dist/honesty/uncaptured-bodies.d.ts

@@ -8,12 +8,14 @@
  * every other field in the record agrees is a clean 200.
  *
  * So an omission is declared rather than left to inference, with the one line that fixes it. Present
- * only when a body-bearing call was returned AND none of them carried a body, so an app that already
- * captures bodies pays nothing and the field's PRESENCE is the warning.
+ * only when a body-bearing call was returned AND no body — request or response — was recorded
+ * anywhere in the result, so an app that already captures bodies pays nothing and the field's
+ * PRESENCE is the warning.
  */
 export declare function bodiesNotCaptured(calls: {
     method?: string;
     requestBody?: string;
+    responseBody?: string;
 }[]): {
     bodiesNotCaptured?: string;
 };

package/dist/honesty/uncaptured-bodies.js

@@ -10,13 +10,20 @@ const BODY_BEARING_METHODS = new Set(['POST', 'PUT', 'PATCH']);
  * every other field in the record agrees is a clean 200.
  *
  * So an omission is declared rather than left to inference, with the one line that fixes it. Present
- * only when a body-bearing call was returned AND none of them carried a body, so an app that already
- * captures bodies pays nothing and the field's PRESENCE is the warning.
+ * only when a body-bearing call was returned AND no body — request or response — was recorded
+ * anywhere in the result, so an app that already captures bodies pays nothing and the field's
+ * PRESENCE is the warning.
  */
 export function bodiesNotCaptured(calls) {
     const bodyBearing = calls.filter((c) => BODY_BEARING_METHODS.has((c.method ?? '').toUpperCase()));
     if (0 === bodyBearing.length)
         return {};
+    // A recorded response body anywhere in the result proves capture is ON. An absent request body
+    // then means this payload was not stringified (a multipart upload, a body the SDK skipped), not
+    // that recording is off — and firing the note would contradict the body sitting in the same
+    // result, exactly on the question the note exists to answer. (#394)
+    if (calls.some((c) => c.responseBody !== undefined))
+        return {};
     if (bodyBearing.some((c) => c.requestBody !== undefined))
         return {};
     return {

package/dist/honesty/unread-outcome.d.ts

@@ -1,2 +1,10 @@
 import { type ReticleEvent } from '@reticlehq/core';
+/**
+ * The writes whose outcome went unread, as "METHOD url".
+ *
+ * Named rather than counted, because a caveat an agent cannot locate is a caveat it learns to skip.
+ * The sentence used to say "a write returned 2xx with a response body that was never recorded" and
+ * name no write, which is unactionable on any page that makes more than one call.
+ */
+export declare function unreadWriteLabels(events: readonly ReticleEvent[]): string[];
 export declare function hasUnreadWriteOutcome(events: readonly ReticleEvent[]): boolean;

package/dist/honesty/unread-outcome.js

@@ -1,4 +1,5 @@
-import { EventType, MUTATING_METHODS, NetInitiator } from '@reticlehq/core';
+import { EventType, MUTATING_METHODS, NetInitiator, isDevToolingUrl, } from '@reticlehq/core';
+import { asString } from '../tools/tools-helpers.js';
 const IPC_METHOD = NetInitiator.IPC.toUpperCase();
 /**
  * A write whose outcome is sitting in a payload nobody read.
@@ -29,22 +30,48 @@ const IPC_METHOD = NetInitiator.IPC.toUpperCase();
  *    The residual gap is real and narrower: a handler that RESOLVES with a failure inside its payload
  *    is invisible without body capture. That case is `findBodyFailures`, which reads the payload and
  *    catches it precisely — with capture on, where it belongs.
+ *
+ *  - **the app's own traffic only.** The DEV TOOLCHAIN writes too: Next's overlay answers
+ *    `POST /__nextjs_original-stack-frames` with a JSON body the moment the app logs one React
+ *    warning, and nothing captures it. Judged as the app's write, that made every verdict in a Next
+ *    dev app `unknown` — decided by a channel the caller never asked about, on a request the app did
+ *    not make. `findContradictions` has split this traffic out for the same reason since the overlay
+ *    turned correct navigations red; this rule was reading the unsplit window.
  */
 const OK_MIN = 200;
 const OK_MAX = 300;
-export function hasUnreadWriteOutcome(events) {
-    return events.some((event) => {
+/**
+ * The writes whose outcome went unread, as "METHOD url".
+ *
+ * Named rather than counted, because a caveat an agent cannot locate is a caveat it learns to skip.
+ * The sentence used to say "a write returned 2xx with a response body that was never recorded" and
+ * name no write, which is unactionable on any page that makes more than one call.
+ */
+export function unreadWriteLabels(events) {
+    const labels = [];
+    for (const event of events) {
         if (event.type !== EventType.NET_REQUEST)
-            return false;
+            continue;
         const method = ('string' === typeof event.data['method'] ? event.data['method'] : '').toUpperCase();
         if (method === IPC_METHOD || !MUTATING_METHODS.includes(method))
-            return false;
+            continue;
+        const url = asString(event.data['url']);
+        if (isDevToolingUrl(url))
+            continue;
         const status = event.data['status'];
         if (typeof status !== 'number' || status < OK_MIN || status >= OK_MAX)
-            return false;
+            continue;
         if (event.data['responseBody'] !== undefined)
-            return false; // read — findBodyFailures judged it
+            continue; // read — findBodyFailures judged it
         const size = event.data['responseSize'];
-        return 'number' === typeof size && size > 0;
-    });
+        if ('number' !== typeof size || size <= 0)
+            continue;
+        const label = `${method} ${url ?? ''}`.trim();
+        if (!labels.includes(label))
+            labels.push(label);
+    }
+    return labels;
+}
+export function hasUnreadWriteOutcome(events) {
+    return unreadWriteLabels(events).length > 0;
 }

package/dist/honesty/unsettled.d.ts

@@ -21,6 +21,15 @@ export interface UnsettledWindow {
     waitedFor: string;
     /** Requests that started in this window and had not come back, as "METHOD url". */
     stillInFlight: readonly string[];
+    /**
+     * Endpoints called more than once in this window, as "METHOD url ×N" — see `repeatedRequestLabels`.
+     *
+     * The case `stillInFlight` structurally cannot see: a retry loop against a dead backend completes
+     * every attempt, so nothing is ever outstanding, and the verdict fell through to a sentence that
+     * blamed unnamed churn on an app whose whole problem was one endpoint being hammered. Optional —
+     * a caller that does not supply it gets exactly the sentence that shipped before.
+     */
+    repeated?: readonly string[];
 }
 /**
  * The wait, in one phrase.

package/dist/honesty/unsettled.js

@@ -64,10 +64,14 @@ export function unsettledBecause(base, window) {
     if (window === undefined)
         return `${base} — re-check, or assert a consequence that settles`;
     if (0 === window.stillInFlight.length) {
+        const repeated = window.repeated ?? [];
         return (`${base}. It waited for ${window.waitedFor}, and no request started in this window was left ` +
-            'open — what kept the page busy was its own churn (a poll, a timer, an animation), so waiting ' +
-            'longer will not help. Assert the consequence you care about (a signal, a route change, or ' +
-            'store state) instead of waiting for idle, and re-check if the app is genuinely slow');
+            'open — what kept the page busy was its own churn ' +
+            (0 === repeated.length
+                ? '(a poll, a timer, an animation)'
+                : `(these fired repeatedly: ${repeated.join(', ')} — a poll or a retrying query)`) +
+            ', so waiting longer will not help. Assert the consequence you care about (a signal, a route ' +
+            'change, or store state) instead of waiting for idle, and re-check if the app is genuinely slow');
     }
     const shown = window.stillInFlight.slice(0, MAX_LISTED_REQUESTS);
     const rest = window.stillInFlight.length - shown.length;