@reticlehq/server 2.13.1 → 2.14.0

package/dist/flows/predicate-to-expect.js

@@ -96,16 +96,22 @@ export function predicateToExpect(predicate) {
  * `reticle_verify` then correctly called it `unverifiable` — the record → save → verify path
  * completing all the way to a run that could never be a pass. Found by driving it.
  *
- * The list below is exactly what `successToPredicate` reads, plus the testid the step runner
- * asserts directly against the DOM. Anything it cannot compile is still dropped.
+ * The list below is exactly what `successToPredicate` reads, including an element located by
+ * role or name. A testid is also asserted directly against the DOM by the step runner. Anything
+ * it cannot compile is still dropped.
  */
 export function enforcedOnReplay(expect) {
     if (expect === undefined)
         return undefined;
     const kept = {};
-    // The step runner asserts this one directly against the live DOM, before the predicate engine.
-    if (expect.element?.testid !== undefined)
-        kept.element = expect.element;
+    // The step runner asserts a testid against the live DOM before the predicate engine. Role and
+    // name are not that path: successToPredicate compiles them, and dropping them here made a
+    // recorded `until` by button name vanish so the saved flow could not go red.
+    const element = expect.element;
+    if (undefined !== element &&
+        (undefined !== element.testid || undefined !== element.role || undefined !== element.name)) {
+        kept.element = element;
+    }
     // Everything `successToPredicate` can compile. Replay evaluates EVERY kind of expect through it
     // (see assertStepExpect); this list is what that function actually reads.
     if (expect.state !== undefined)

package/dist/flows/recording-backtrack.d.ts

@@ -0,0 +1,24 @@
+/**
+ * A recorded flow that backtracks across pages cannot replay.
+ *
+ * The recorder stores clicks, not navigations. A drive that opens a product and then returns to
+ * search saves both clicks; replay lands on the product page and looks for a control that only
+ * exists on search. That shape is visible from the route list with no change to the flow file, so
+ * stop/save can warn instead of writing a flow that fails on the next click.
+ */
+import { type ReticleEvent } from '@reticlehq/core';
+/**
+ * The page a recording step sat on, comparable across path routers and hash routers.
+ *
+ * A startPath is stored as pathname+hash (`/#/search`); a ROUTE_CHANGE carries them separately.
+ * Without this, every hash-router page compares as `/` and a backtrack is invisible.
+ */
+export declare function recordingRouteOf(pathname: string, hash?: string): string;
+/**
+ * Warn when the journey left a page and came back. Linear A→B→C is silent: that still cannot
+ * replay either if a later click needs a previous page, but the reported failure is specifically
+ * the backtrack, and inventing a warning for every multi-page drive would teach agents to ignore it.
+ */
+export declare function recordingBacktrackWarning(routes: readonly string[]): string | undefined;
+/** Ordered pages the recording sat on, startPath first, consecutive stays collapsed. */
+export declare function routesFromRecording(startPath: string | undefined, events: readonly ReticleEvent[]): string[];

package/dist/flows/recording-backtrack.js

@@ -0,0 +1,73 @@
+/**
+ * A recorded flow that backtracks across pages cannot replay.
+ *
+ * The recorder stores clicks, not navigations. A drive that opens a product and then returns to
+ * search saves both clicks; replay lands on the product page and looks for a control that only
+ * exists on search. That shape is visible from the route list with no change to the flow file, so
+ * stop/save can warn instead of writing a flow that fails on the next click.
+ */
+import { EventType } from '@reticlehq/core';
+import { routePathOf } from '../events/predicate-route.js';
+function asString(value) {
+    return 'string' === typeof value ? value : undefined;
+}
+/**
+ * The page a recording step sat on, comparable across path routers and hash routers.
+ *
+ * A startPath is stored as pathname+hash (`/#/search`); a ROUTE_CHANGE carries them separately.
+ * Without this, every hash-router page compares as `/` and a backtrack is invisible.
+ */
+export function recordingRouteOf(pathname, hash = '') {
+    const hashIdx = pathname.indexOf('#/');
+    if (hashIdx >= 0) {
+        return routePathOf(pathname.slice(0, hashIdx) || '/', pathname.slice(hashIdx));
+    }
+    const fragment = hash.startsWith('#') ? hash : 0 === hash.length ? '' : `#${hash}`;
+    if (fragment.startsWith('#/'))
+        return routePathOf(0 === pathname.length ? '/' : pathname, fragment);
+    return pathname;
+}
+function collapseConsecutive(routes) {
+    const out = [];
+    for (const route of routes) {
+        if (0 === route.length)
+            continue;
+        if (out.at(-1) === route)
+            continue;
+        out.push(route);
+    }
+    return out;
+}
+/**
+ * Warn when the journey left a page and came back. Linear A→B→C is silent: that still cannot
+ * replay either if a later click needs a previous page, but the reported failure is specifically
+ * the backtrack, and inventing a warning for every multi-page drive would teach agents to ignore it.
+ */
+export function recordingBacktrackWarning(routes) {
+    const path = collapseConsecutive(routes);
+    const seen = new Set();
+    for (const route of path) {
+        if (seen.has(route)) {
+            return (`this recording returned to ${route} after leaving it — replay has no navigation steps, so ` +
+                'the next click looks for a control that only exists on a page the tab is no longer on. ' +
+                `Journey: ${path.join(' → ')}. Split into one flow per page, or record the control that navigates back.`);
+        }
+        seen.add(route);
+    }
+    return undefined;
+}
+/** Ordered pages the recording sat on, startPath first, consecutive stays collapsed. */
+export function routesFromRecording(startPath, events) {
+    const raw = [];
+    if (undefined !== startPath)
+        raw.push(recordingRouteOf(startPath));
+    for (const event of events) {
+        if (EventType.ROUTE_CHANGE !== event.type)
+            continue;
+        const pathname = asString(event.data['pathname']) ?? asString(event.data['to']);
+        if (undefined === pathname)
+            continue;
+        raw.push(recordingRouteOf(pathname, asString(event.data['hash']) ?? ''));
+    }
+    return collapseConsecutive(raw);
+}

package/dist/flows/recordings.d.ts

@@ -22,6 +22,12 @@ export interface CompiledProgram {
     version: number;
     steps: RecordedStep[];
     startPath?: string;
+    /**
+     * Pages the recording sat on, in order, consecutive stays collapsed. In-memory only — not written
+     * to the flow file. Lets save warn about a backtrack (a journey that cannot replay) without a
+     * format change.
+     */
+    routes?: string[];
 }
 /**
  * Tracks in-flight recordings (name -> { buffer cursor at record_start, captured steps })

package/dist/flows/replay-halt.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Whether a replay stopped before the end of the flow, and how much it never reached.
+ *
+ * `replayFlow` breaks on the first failing step. That is right — once a consequence did not hold,
+ * every later step would run against a state the flow never described, and continuing would turn
+ * one wrong result into several. What was missing is any way for the caller to SEE it: a two-step
+ * flow that halted comes back with one step result, and a reader who does not know the halt rule
+ * sees a step that is simply absent.
+ *
+ * Reported as "replay silently skips a second destructive step" — with three correct observations
+ * and a wrong conclusion, because the output offered no other reading.
+ */
+import type { FlowStepResult } from '@reticlehq/core';
+/** Set on a replay that stopped early; omitted entirely otherwise, so a clean pass stays flat. */
+export interface ReplayHalt {
+    /** Index of the step that stopped the run. */
+    atStep: number;
+    /** How many of the flow's steps were never attempted because of it. */
+    notAttempted: number;
+}
+/**
+ * `total` is the FLOW's step count, deliberately — not `results.length`. The results array is the
+ * short one, so deriving the total from it would report zero skipped on every halt, which is the
+ * defect restated as its own fix.
+ */
+export declare function haltedFrom(results: readonly FlowStepResult[], total: number): ReplayHalt | undefined;

package/dist/flows/replay-halt.js

@@ -0,0 +1,30 @@
+/**
+ * Whether a replay stopped before the end of the flow, and how much it never reached.
+ *
+ * `replayFlow` breaks on the first failing step. That is right — once a consequence did not hold,
+ * every later step would run against a state the flow never described, and continuing would turn
+ * one wrong result into several. What was missing is any way for the caller to SEE it: a two-step
+ * flow that halted comes back with one step result, and a reader who does not know the halt rule
+ * sees a step that is simply absent.
+ *
+ * Reported as "replay silently skips a second destructive step" — with three correct observations
+ * and a wrong conclusion, because the output offered no other reading.
+ */
+/**
+ * `total` is the FLOW's step count, deliberately — not `results.length`. The results array is the
+ * short one, so deriving the total from it would report zero skipped on every halt, which is the
+ * defect restated as its own fix.
+ */
+export function haltedFrom(results, total) {
+    const last = results[results.length - 1];
+    if (last === undefined)
+        return undefined;
+    if (last.ok && last.drift === undefined)
+        return undefined;
+    const notAttempted = total - results.length;
+    // A failure on the FINAL step is not a halt: nothing was left to attempt, and `notAttempted: 0`
+    // would send a reader looking for steps that do not exist.
+    if (notAttempted <= 0)
+        return undefined;
+    return { atStep: last.step, notAttempted };
+}

package/dist/flows/replay.d.ts

@@ -13,14 +13,6 @@ export declare function ambiguousTestidNote(value: string): string;
  * resolution — can't drift between them.
  */
 export declare function queryRefs(result: CommandResult): string[];
-/**
- * The environment variable that supplies one redacted field.
- *
- * Named after the field so it is guessable from the flow alone: `auth-password` is read from
- * `RETICLE_SECRET_AUTH_PASSWORD`. A scheme requiring a lookup table would mean the flow says a
- * value is missing and cannot say what to set.
- */
-export declare const secretEnvKey: (field: string) => string;
 /**
  * A destructive-action confirmation is one-shot and must never persist into a recording.
  *

package/dist/flows/replay.js

@@ -31,7 +31,7 @@ export function queryRefs(result) {
  * `RETICLE_SECRET_AUTH_PASSWORD`. A scheme requiring a lookup table would mean the flow says a
  * value is missing and cannot say what to set.
  */
-export const secretEnvKey = (field) => `RETICLE_SECRET_${field.replace(/[^a-zA-Z0-9]+/g, '_').toUpperCase()}`;
+const secretEnvKey = (field) => `RETICLE_SECRET_${field.replace(/[^a-zA-Z0-9]+/g, '_').toUpperCase()}`;
 /**
  * A destructive-action confirmation is one-shot and must never persist into a recording.
  *
@@ -57,6 +57,18 @@ export function replayActionArgs(value, confirmDangerous = false, field) {
     }
     return args;
 }
+/**
+ * The field a compiled recording step names — the same mapping `anchorFieldName` uses on a
+ * FlowAnchor, read off the `by`/`value`/`name` shape `compileAnchorArgs` emits.
+ */
+function recordedFieldName(step) {
+    const by = asString(step['by']);
+    if (QueryBy.TESTID === by)
+        return asString(step['value']);
+    if (QueryBy.ROLE === by)
+        return asString(step['name']);
+    return undefined;
+}
 /** The element's source location from an action result, when the framework stamped one. */
 function sourceFromResult(res) {
     const source = asRecord(res['source']);
@@ -265,7 +277,7 @@ export async function replayProgram(session, program, confirmDangerous = false)
                     liveSteps.push({
                         ref,
                         action: asString(sub['action']) ?? '',
-                        args: replayActionArgs(sub['args'], confirmDangerous),
+                        args: replayActionArgs(sub['args'], confirmDangerous, recordedFieldName(sub)),
                     });
                 }
                 // Attribute the step's effects to the step: unattributed effects are learned as ambient
@@ -293,7 +305,7 @@ export async function replayProgram(session, program, confirmDangerous = false)
                     r = await session.command(ReticleCommand.ACT, {
                         ref,
                         action: asString(step.args['action']) ?? '',
-                        args: replayActionArgs(step.args['args'], confirmDangerous),
+                        args: replayActionArgs(step.args['args'], confirmDangerous, recordedFieldName(step.args)),
                     });
                 }
                 finally {

package/dist/flows/suite-flakes.d.ts

@@ -18,7 +18,7 @@
 import { ReplayStatus } from '@reticlehq/core';
 import type { FileSystemPort } from '../project/fs-port.js';
 /** Just the shape this needs from a replay — so a test does not have to build a whole result. */
-export interface FlakeOutcome {
+interface FlakeOutcome {
     readonly name: string;
     readonly status: ReplayStatus;
 }
@@ -31,3 +31,4 @@ export interface FlakeOutcome {
 export declare function recordSuiteFlakes(fs: FileSystemPort, reticleRoot: string, runs: readonly {
     readonly replay: FlakeOutcome;
 }[]): Promise<readonly string[]>;
+export {};

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

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { sessionRoot } from '../project/session-root.js';
+import { sessionRoot, sessionProjectId } from '../project/session-root.js';
 import { verdictForSuite } from './verify-change-verdict.js';
 import { attributedFailures } from './attributed-failure.js';
 import { Verified } from '@reticlehq/core';
@@ -62,16 +62,28 @@ export const VERIFY_CHANGE_TOOLS = [
                 ? args['files'].filter((f) => 'string' === typeof f)
                 : [];
             const since = asString(args['since']);
-            const changedFiles = await resolveChangedFiles(files, since);
+            // The daemon's cwd is not the project — it is wherever the MCP host started it, which for a
+            // globally-registered server is `/` or `$HOME`. `deps.reticleRoot` is the project directory
+            // this daemon was configured with, and it is the right tree to diff.
+            const changed = await resolveChangedFiles(files, since, deps.reticleRoot);
+            const changedFiles = changed.files;
             // Same root flow_save wrote to. A read that resolved differently would report "no flows
             // covered this change" over flows that exist, which reads as a clean result rather than
             // an error, so the disagreement would be invisible.
-            const flows = await loadNamedFlows(deps.fs, sessionRoot(deps, asString(args['sessionId'])));
+            // Both halves of the address from one place. The root was already resolved from the session;
+            // the id used to come from the daemon's cwd, so they named different projects.
+            const sid = asString(args['sessionId']);
+            const flows = await loadNamedFlows(deps.fs, sessionRoot(deps, sid), sessionProjectId(deps, sid));
             const { affected, unknownProvenance } = affectedSavedFlows(flows, changedFiles);
             if (0 === changedFiles.length) {
                 return {
                     verified: Verified.UNKNOWN,
-                    because: 'no changed files were given, so there was nothing to decide about',
+                    // A git failure and a clean tree both arrive here with no files, and they are opposite
+                    // answers: one means there was nothing to decide about, the other means the question was
+                    // never asked. `unknown` is right either way, but the REASON is what the caller acts on.
+                    because: changed.failed
+                        ? `could not read the diff for \`${String(since)}\`, so nothing was compared: ${changed.reason ?? 'git failed'}`
+                        : 'no changed files were given, so there was nothing to decide about',
                     changedFiles,
                     flowsRun: [],
                     unknownProvenance,

package/dist/honesty/already-true.d.ts

@@ -1,2 +1,16 @@
 import type { Predicate } from '../events/predicate.js';
 export declare function readsDomState(predicate: Predicate): boolean;
+/**
+ * #889: an `already_true` verdict says the declared consequence held before the action, so nothing
+ * was proven — but a `text`/`element` predicate matches DOM presence by default, not visibility (a
+ * caller has to pass `visible: true` to ask for that). A dialog's content mounted-but-hidden before
+ * the click therefore reads as "already true", identically to genuinely-visible content that was
+ * already on screen — and the `already_true` message named neither which node it matched nor that
+ * the match was invisible, which is what made it read as proof of nothing rather than as the
+ * mid-load/hidden-mount trap it actually was.
+ *
+ * True only when the predicate itself did not ask for a state (an explicit `visible`/other state
+ * constraint already means the caller saw and handled this) AND every matched element is hidden —
+ * one visible match among several is a fair, ordinary read and is left alone.
+ */
+export declare function alreadyTrueHiddenMatch(predicate: Predicate, evidence: unknown): boolean;

package/dist/honesty/already-true.js

@@ -1,15 +1,17 @@
 /**
  * Which predicates can be satisfied by something that was already true before the action.
  *
- * Event-based kinds (net, signal, route, console, animation, settled) are evaluated against the
+ * Event-based kinds (net, signal, console, animation, settled) are evaluated against the
  * event buffer floored at the act's own cursor, so a stale event cannot satisfy them — that floor is
- * why `act_and_wait` can trust them at all. `state` is read through the same floored path.
+ * why `act_and_wait` can trust them at all.
  *
- * `element` and `text` read the LIVE DOM, where no floor exists. A condition that held before the
+ * `element` and `text` read the LIVE DOM, `route` can fall back to the current route, and `state` reads
+ * live store memory via STATE_READ — where no event floor applies. A condition that held before the
  * click holds after it and passes instantly, whatever the action did. Measured in the field: a click
  * asserted with `{ kind: 'text', contains: 'Parallel Routes' }` returned `verified: "yes"` in 478ms
  * against `routeChanges: 0`, because the predicate matched the nav link that was already on screen —
- * the real navigation landed 1.8 seconds later.
+ * the real navigation landed 1.8 seconds later. Similarly, a pre-existing store value (e.g. cart.count == 3)
+ * satisfies an inert action if not checked before dispatch.
  *
  * So these are the kinds worth evaluating BEFORE the act, to find out whether the green means
  * anything.
@@ -31,9 +33,15 @@ export function readsDomState(predicate) {
         // 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.
+        //
+        // STATE is here for the same reason: it is evaluated via STATE_READ against live in-memory stores
+        // rather than through the floored event buffer. If the store already holds the expected value
+        // before dispatch, an inert click would immediately pass post-dispatch on the pre-existing state.
+        // Evaluating before dispatch routes that pre-existing condition into already_true.
         case PredicateKind.ELEMENT:
         case PredicateKind.TEXT:
         case PredicateKind.ROUTE:
+        case PredicateKind.STATE:
             return true;
         case PredicateKind.ALL_OF:
         case PredicateKind.ANY_OF:
@@ -44,3 +52,38 @@ export function readsDomState(predicate) {
             return false;
     }
 }
+/** True when `value` looks like an element/text predicate's passing evidence — an array of descriptors. */
+function isDescriptorArray(value) {
+    if (!Array.isArray(value))
+        return false;
+    return value.every((v) => {
+        if ('object' !== typeof v || null === v)
+            return false;
+        return 'boolean' === typeof v['visible'];
+    });
+}
+/**
+ * #889: an `already_true` verdict says the declared consequence held before the action, so nothing
+ * was proven — but a `text`/`element` predicate matches DOM presence by default, not visibility (a
+ * caller has to pass `visible: true` to ask for that). A dialog's content mounted-but-hidden before
+ * the click therefore reads as "already true", identically to genuinely-visible content that was
+ * already on screen — and the `already_true` message named neither which node it matched nor that
+ * the match was invisible, which is what made it read as proof of nothing rather than as the
+ * mid-load/hidden-mount trap it actually was.
+ *
+ * True only when the predicate itself did not ask for a state (an explicit `visible`/other state
+ * constraint already means the caller saw and handled this) AND every matched element is hidden —
+ * one visible match among several is a fair, ordinary read and is left alone.
+ */
+export function alreadyTrueHiddenMatch(predicate, evidence) {
+    if (predicate.kind !== PredicateKind.ELEMENT && predicate.kind !== PredicateKind.TEXT) {
+        return false;
+    }
+    if (predicate.kind === PredicateKind.ELEMENT && predicate.state !== undefined)
+        return false;
+    if (predicate.kind === PredicateKind.TEXT && true === predicate.visible)
+        return false;
+    if (!isDescriptorArray(evidence) || 0 === evidence.length)
+        return false;
+    return evidence.every((el) => !el.visible);
+}

package/dist/honesty/blind-spots.d.ts

@@ -6,7 +6,7 @@
  */
 export { BlindSpotKind } from '@reticlehq/core';
 import { BlindSpotKind, type ReticleEvent } from '@reticlehq/core';
-export interface BlindSpot {
+interface BlindSpot {
     kind: BlindSpotKind;
     count: number;
 }
@@ -89,6 +89,7 @@ interface AbsencePredicate {
     query?: {
         scope?: unknown;
     };
+    predicate?: AbsencePredicate;
 }
 /**
  * When an absence assertion targets a page with regions Reticle cannot observe, "the element is
@@ -127,5 +128,6 @@ export declare function isStateUnwatched(spots: readonly BlindSpot[]): boolean;
 export declare function restsOnCompleteWindow(predicate: {
     kind: string;
     absent?: boolean;
+    count?: number;
     predicate?: unknown;
 }): boolean;

package/dist/honesty/blind-spots.js

@@ -176,7 +176,19 @@ function droppedByTransport(events) {
  *   - CLOSED_SHADOW_ROOT — a subtree Reticle cannot see into
  */
 export function absenceBlindSpotNote(predicate, spots) {
-    if ('element' !== predicate.kind || true !== predicate.absent)
+    // `not(element)` is the third spelling of an absence assertion — the `not` wrapper IS the
+    // negation, so the inner predicate will not carry `absent: true`. Unwrap and synthesize it.
+    // `not(element { absent: true })` is a double negative — presence — and a positive match is
+    // not threatened by an unobservable region.
+    if (PredicateKind.NOT === predicate.kind && predicate.predicate !== undefined) {
+        if (PredicateKind.ELEMENT === predicate.predicate.kind) {
+            if (true === predicate.predicate.absent)
+                return undefined;
+            return absenceBlindSpotNote({ ...predicate.predicate, absent: true }, spots);
+        }
+        return undefined;
+    }
+    if (PredicateKind.ELEMENT !== predicate.kind || true !== predicate.absent)
         return undefined;
     const relevant = spots.filter((spot) => spot.count > 0 &&
         (spot.kind === BlindSpotKind.CROSS_ORIGIN_IFRAME
@@ -221,5 +233,16 @@ export function isStateUnwatched(spots) {
 export function restsOnCompleteWindow(predicate) {
     if (PredicateKind.NOT === predicate.kind)
         return true;
+    // An exact cardinality of ZERO is the third spelling of an absence claim, and reading only
+    // `absent` missed it: `{ kind: "net", urlContains: "/api/auth/sign-in", count: 0 }` says "this
+    // request was never made", and the call the buffer evicted is precisely the disproof. It was
+    // graded `yes` over a window known to have lost scarce evidence — the exact false green the two
+    // clauses above exist to prevent, reached by the one spelling they did not cover (#668).
+    //
+    // Only zero. `count: 2` asserts calls were MADE and found them; events aged out elsewhere in the
+    // buffer do not unmake a positive finding, which is the same reason a plain presence assertion is
+    // left alone here.
+    if (0 === predicate.count)
+        return true;
     return true === predicate.absent;
 }

package/dist/honesty/body-capture-remedy.d.ts

@@ -0,0 +1,42 @@
+/**
+ * What to tell a caller whose assertion needs response bodies, given what the connected SDK can do.
+ *
+ * The remedy used to be one fixed sentence naming `captureNetworkBodies`. Reported from the field:
+ * six verdicts came back `unknown`/`outcome_unread` advising that setting against a pinned
+ * `@reticlehq/react` from before it existed. The reporter set the env var, restarted, got the
+ * identical message, and worked it out by elimination.
+ *
+ * The daemon is TOLD the page's SDK version at HELLO and threw it away after computing skew. Nothing
+ * new has to be observed to say the true thing — it only has to be kept.
+ *
+ * Same class as the version-skew remedy that named a React package on Vue projects: remedy text that
+ * does not check whether it applies. A wrong remedy is worse than none, because it is followed.
+ */
+/** The release that introduced `captureNetworkBodies` — see the browser observer's history. */
+export declare const BODY_CAPTURE_MIN_VERSION = "2.4.0";
+/**
+ * The remedy for this session, or the honest statement that there is none.
+ *
+ * An UNKNOWN version is treated as capable. A hand-wired connect reports none, and guessing "too
+ * old" there would hide a working fix from someone who could have used it; the opposite guess costs
+ * one wasted read. The asymmetry decides it.
+ */
+export declare function bodyCaptureRemedy(sdkVersion: string | undefined): string;
+/**
+ * Refuse a body clause the session cannot answer, BEFORE the action is spent.
+ *
+ * Reported: an `act_and_wait` matched the right call and returned `verified: "no"` with "a matching
+ * call with no recorded body", because that project's `connect()` does not pass
+ * `captureNetworkBodies` — and the reporter could not change it, since it was not their project's
+ * config to edit for an unrelated verification task. The action bought nothing that was not knowable
+ * in advance, and on a drive that mutates state an action is not always repeatable. That is what
+ * makes this a pre-flight rather than a better failure message.
+ *
+ * Refuses ONLY on a DECLARED `captureBodies: false`. An SDK too old to announce the setting sends
+ * nothing, and refusing on silence would break every session predating the announcement for a clause
+ * many of them satisfy — the same asymmetry that makes an unknown VERSION count as capable.
+ */
+export declare function bodyClauseRefusal(predicate: unknown, session: {
+    captureBodies?: boolean | undefined;
+    sdkVersion?: string | undefined;
+}): string | undefined;

package/dist/honesty/body-capture-remedy.js

@@ -0,0 +1,95 @@
+/**
+ * What to tell a caller whose assertion needs response bodies, given what the connected SDK can do.
+ *
+ * The remedy used to be one fixed sentence naming `captureNetworkBodies`. Reported from the field:
+ * six verdicts came back `unknown`/`outcome_unread` advising that setting against a pinned
+ * `@reticlehq/react` from before it existed. The reporter set the env var, restarted, got the
+ * identical message, and worked it out by elimination.
+ *
+ * The daemon is TOLD the page's SDK version at HELLO and threw it away after computing skew. Nothing
+ * new has to be observed to say the true thing — it only has to be kept.
+ *
+ * Same class as the version-skew remedy that named a React package on Vue projects: remedy text that
+ * does not check whether it applies. A wrong remedy is worse than none, because it is followed.
+ */
+/** The release that introduced `captureNetworkBodies` — see the browser observer's history. */
+export const BODY_CAPTURE_MIN_VERSION = '2.4.0';
+/**
+ * Compare two dotted versions numerically.
+ *
+ * String comparison inverts exactly where it hurts: `'2.10.0' < '2.4.0'` lexically, so a NEWER SDK
+ * would be told it is too old and the working remedy withheld. A prerelease suffix is dropped rather
+ * than parsed — `2.13.0-rc.1` is 2.13 for this question, and nothing here needs finer.
+ */
+function isAtLeast(version, minimum) {
+    const parts = (v) => v
+        .split('-')[0]
+        ?.split('.')
+        .map((n) => Number.parseInt(n, 10) || 0) ?? [];
+    const have = parts(version);
+    const want = parts(minimum);
+    for (let i = 0; i < Math.max(have.length, want.length); i += 1) {
+        const a = have[i] ?? 0;
+        const b = want[i] ?? 0;
+        if (a !== b)
+            return a > b;
+    }
+    return true;
+}
+/** The sentence naming the setting — only ever produced for an SDK that HAS it. */
+const ENABLE_IT = 'Turn it on where your app calls connect(): `reticle.connect({ captureNetworkBodies: true })`, ' +
+    'or for the Vite plugin `reticle({ captureNetworkBodies: true })` / VITE_RETICLE_CAPTURE_BODIES=1. ' +
+    'Then re-run the action.';
+/**
+ * The remedy for this session, or the honest statement that there is none.
+ *
+ * An UNKNOWN version is treated as capable. A hand-wired connect reports none, and guessing "too
+ * old" there would hide a working fix from someone who could have used it; the opposite guess costs
+ * one wasted read. The asymmetry decides it.
+ */
+export function bodyCaptureRemedy(sdkVersion) {
+    if (sdkVersion !== undefined && !isAtLeast(sdkVersion, BODY_CAPTURE_MIN_VERSION)) {
+        return (`this page's SDK is ${sdkVersion}, and body capture needs ${BODY_CAPTURE_MIN_VERSION} or ` +
+            'newer — the setting does not exist in your version, so there is nothing to switch on. ' +
+            'Upgrade the SDK, or assert on something else this session can see.');
+    }
+    return ENABLE_IT;
+}
+/** Clause names that can only be answered from a recorded body. */
+const BODY_CLAUSE_FIELDS = ['bodyContains', 'requestBodyContains'];
+/** Does this predicate, or anything nested in it, ask about a body? */
+function asksAboutBody(predicate) {
+    if (null === predicate || 'object' !== typeof predicate)
+        return false;
+    const node = predicate;
+    if (BODY_CLAUSE_FIELDS.some((f) => node[f] !== undefined))
+        return true;
+    // The reported shape is an `allOf` carrying route + console + the net clause that needs bodies.
+    // Checking only the top level would miss every realistic call.
+    const nested = node['predicates'] ?? node['predicate'];
+    if (Array.isArray(nested))
+        return nested.some(asksAboutBody);
+    return asksAboutBody(nested);
+}
+/**
+ * Refuse a body clause the session cannot answer, BEFORE the action is spent.
+ *
+ * Reported: an `act_and_wait` matched the right call and returned `verified: "no"` with "a matching
+ * call with no recorded body", because that project's `connect()` does not pass
+ * `captureNetworkBodies` — and the reporter could not change it, since it was not their project's
+ * config to edit for an unrelated verification task. The action bought nothing that was not knowable
+ * in advance, and on a drive that mutates state an action is not always repeatable. That is what
+ * makes this a pre-flight rather than a better failure message.
+ *
+ * Refuses ONLY on a DECLARED `captureBodies: false`. An SDK too old to announce the setting sends
+ * nothing, and refusing on silence would break every session predating the announcement for a clause
+ * many of them satisfy — the same asymmetry that makes an unknown VERSION count as capable.
+ */
+export function bodyClauseRefusal(predicate, session) {
+    if (false !== session.captureBodies)
+        return undefined;
+    if (!asksAboutBody(predicate))
+        return undefined;
+    return ('this assertion reads a request/response BODY, and this session is not recording them — it ' +
+        `would fail whatever the app did. Nothing ran, so no action was spent. ${bodyCaptureRemedy(session.sdkVersion)}`);
+}

package/dist/honesty/feature-capture.d.ts

@@ -1,4 +1,4 @@
-import { type Intent, type JournalAction } from '@reticlehq/core';
+import { type Intent, type JournalAction } from '@reticlehq/core/artifacts';
 /**
  * Were `reticle_context` and `reticle_intent` used at all — and did using them change anything?
  *
@@ -94,7 +94,7 @@ export declare function noteToolDispatched(session: {
     capture?: CaptureLedger;
 }, tool: string): void;
 /** What one session's use of the two features looks like. Everything but `observed` is omitted when nothing was recorded. */
-export interface FeatureCapture {
+interface FeatureCapture {
     /** False when this daemon recorded nothing for the session — "not watched", never "not used". */
     observed: boolean;
     /** The ledger dropped calls, so every count is a floor. Present only when true. */
@@ -148,3 +148,4 @@ export declare function foldFeatureCapture(input: {
     /** The session's dispatched-action count now, so a run that ended on an action is not read as idle. */
     finalActions: number;
 }): FeatureCapture;
+export {};

package/dist/honesty/feature-capture.js

@@ -1,4 +1,4 @@
-import { IntentState, JournalVerdictEffectSchema, RUN_ESTABLISHED_CAP, } from '@reticlehq/core';
+import { IntentState, JournalVerdictEffectSchema, RUN_ESTABLISHED_CAP, } from '@reticlehq/core/artifacts';
 import { subjectOf } from '../runs/run-context.js';
 import { ReticleTool } from '../tools/tool-names.js';
 /**

package/dist/honesty/gap-ledger.d.ts

@@ -1,4 +1,4 @@
-import { type InstrumentationGap } from '@reticlehq/core';
+import { type InstrumentationGap } from '@reticlehq/core/artifacts';
 /**
  * What this session still cannot see, accumulated across its verdicts.
  *