@reticlehq/server 2.2.0 → 2.3.0

package/dist/flows/replay.js

@@ -64,6 +64,24 @@ export function compileActStep(args, res) {
             testidArgs['source'] = source;
         return { tool: ReticleTool.ACT, stable: true, args: testidArgs };
     }
+    // Role + NAME before component: a component/source anchor names the JSX site, so every row's copy
+    // of the same control collapses onto it. The accessible name separates them, and it is also the
+    // only stable anchor an app with no testids has. Measured: three rows' checkboxes compiled to one
+    // identical component anchor and replayed onto a single element.
+    const role = asString(r['role']);
+    const name = asString(r['name']);
+    if (role !== undefined && name !== undefined) {
+        const roleArgs = {
+            by: QueryBy.ROLE,
+            value: role,
+            name,
+            action,
+            args: actArgs,
+        };
+        if (source !== undefined)
+            roleArgs['source'] = source;
+        return { tool: ReticleTool.ACT, stable: true, args: roleArgs };
+    }
     const component = asString(r['component']);
     if (component !== undefined || source !== undefined) {
         const componentArgs = { by: QueryBy.COMPONENT, action, args: actArgs };
@@ -99,7 +117,16 @@ export function compileSequenceStep(args, res) {
     });
     return { tool: ReticleTool.ACT_SEQUENCE, stable, args: { steps: subSteps } };
 }
-/** Resolve a recorded sub-step's element to a live ref via testid query, else fall back to its stored ref. */
+/**
+ * Resolve a recorded step's element to a live ref, by whichever anchor the compiler chose.
+ *
+ * Every anchor the compiler can EMIT must be resolvable here. It could not be: `compileActStep`
+ * emits `by: component` steps (and marks them `stable: true`), and this function only understood
+ * `testid` — so every component-anchored step failed with "no testid or ref to resolve", and the
+ * `stable` flag on it was a claim the replayer could not honour. Measured on a console with 5 steps:
+ * the 2 with testids replayed, the 3 without were unreplayable, and the flow reported ok:false at
+ * the first of them.
+ */
 async function resolveRef(session, step) {
     const by = asString(step.by);
     const value = asString(step.value);
@@ -113,9 +140,50 @@ async function resolveRef(session, step) {
             throw new Error(`testid '${value}' did not resolve in current page`);
         return refs.length > 1 ? { ref, note: ambiguousTestidNote(value) } : { ref };
     }
+    // Role + accessible NAME: the anchor that distinguishes one row's control from another's, which
+    // neither a testid-less app nor a shared JSX source location can do.
+    if (by === QueryBy.ROLE && value !== undefined) {
+        const name = asString(step.name);
+        const query = { by, value, ...(name === undefined ? {} : { name }) };
+        const result = await session.command(ReticleCommand.QUERY, query);
+        if (!result.ok)
+            throw new Error(result.error ?? 'query failed');
+        const ref = queryRefs(result)[0];
+        if (ref === undefined) {
+            throw new Error(`${value} named '${String(name)}' did not resolve in current page`);
+        }
+        return { ref };
+    }
+    if (by === QueryBy.COMPONENT) {
+        const component = asString(step.component);
+        const source = step.source;
+        const query = {
+            by,
+            ...(component === undefined ? {} : { component, value: component }),
+            ...(source === undefined ? {} : { source }),
+        };
+        const result = await session.command(ReticleCommand.QUERY, query);
+        if (!result.ok)
+            throw new Error(result.error ?? 'query failed');
+        const refs = queryRefs(result);
+        const ref = refs[0];
+        if (ref === undefined) {
+            throw new Error(`component '${String(component)}' did not resolve in current page`);
+        }
+        // A source location identifies a JSX SITE, not an instance: one `<input>` inside a row renders
+        // once per row and every one of them shares this anchor. Saying so is the difference between a
+        // replay that repeated itself and a replay that reports it might have.
+        return refs.length > 1
+            ? {
+                ref,
+                note: `component anchor matched ${String(refs.length)} elements — replayed the first`,
+            }
+            : { ref };
+    }
     const ref = asString(step.ref);
-    if (ref === undefined || ref.length === 0)
-        throw new Error('step has no testid or ref to resolve');
+    if (ref === undefined || ref.length === 0) {
+        throw new Error('step has no resolvable anchor (testid, role+name, component) and no ref');
+    }
     return { ref, note: 'replayed by stale ref (not portable across sessions)' };
 }
 /** Re-execute every step of a compiled program in order, stopping at the first failure. */
@@ -190,4 +258,3 @@ function buildResult(tool, ok, error, notes) {
         base.note = notes.join('; ');
     return base;
 }
-//# sourceMappingURL=replay.js.map

package/dist/flows/server-verify.d.ts

@@ -0,0 +1,15 @@
+/**
+ * verify:server delegation. When a project's cloud config sets `verify: 'server'`, the FLOW_VERIFY tool
+ * runs the suite on the hosted runner (POST /v1/verifications) instead of replaying in the local browser,
+ * and maps the server's report back into the SAME SuiteVerdict the local path returns — so the agent's
+ * contract is identical either way. Falls back to local (returns null) when not attached, wrong mode, or
+ * there is no reachable preview URL for the server to hit.
+ */
+import type { SuiteVerdict } from '@reticlehq/core';
+import type { ToolDeps } from '../tools/tools.js';
+import { type ProjectCloud } from './../cloud/cloud-config.js';
+import { type ServerVerification } from '../cloud/cloud-sync.js';
+/** Map the hosted runner's report onto the local suite-verdict shape (status/total/passed/failed/failures). */
+export declare function toSuiteVerdict(report: ServerVerification): SuiteVerdict;
+/** Run the suite on the hosted runner, or null to signal the caller should replay locally. */
+export declare function runServerVerify(deps: ToolDeps, cloud: ProjectCloud, sessionId: string | undefined, flows: string[]): Promise<SuiteVerdict | null>;

package/dist/flows/server-verify.js

@@ -0,0 +1,42 @@
+import { VerifyMode } from './../cloud/cloud-config.js';
+import { submitServerVerification } from '../cloud/cloud-sync.js';
+const PASS = 'pass';
+const UNVERIFIED = 'unverified';
+const SOURCE = 'reticle-mcp';
+/** Map the hosted runner's report onto the local suite-verdict shape (status/total/passed/failed/failures). */
+export function toSuiteVerdict(report) {
+    const failures = report.flows
+        .filter((f) => f.status !== PASS)
+        .map((f) => ({
+        flow: f.name,
+        verdict: 'fail',
+        nextAction: `verified on the server — see report ${report.verificationId}`,
+    }));
+    const total = report.flows.length;
+    const passed = total - failures.length;
+    const status = report.verdict === PASS && failures.length === 0 ? 'pass' : 'fail';
+    return { status, total, passed, failed: failures.length, summary: report.summary, failures };
+}
+/** Run the suite on the hosted runner, or null to signal the caller should replay locally. */
+export async function runServerVerify(deps, cloud, sessionId, flows) {
+    if (cloud.verify !== VerifyMode.SERVER || cloud.config === null)
+        return null;
+    let previewUrl;
+    try {
+        previewUrl = deps.sessions.resolve(sessionId).url;
+    }
+    catch {
+        previewUrl = undefined;
+    }
+    // The server hits the URL itself; with no URL (or a localhost one it can't reach) fall back to local.
+    if (previewUrl === undefined || previewUrl.length === 0)
+        return null;
+    const report = await submitServerVerification({ previewUrl, flows, source: SOURCE }, cloud.config, (url, init) => fetch(url, init));
+    if (report === null)
+        return null;
+    // The hosted runner said it couldn't actually verify (e.g. it's not enabled yet). Never surface that as
+    // a pass or a fail — fall back to the real local replay so the verdict reflects a browser that ran.
+    if (report.verdict === UNVERIFIED)
+        return null;
+    return toSuiteVerdict(report);
+}

package/dist/flows/verify-change-tools.d.ts

@@ -0,0 +1,2 @@
+import type { ToolDef } from '../tools/tools.js';
+export declare const VERIFY_CHANGE_TOOLS: ToolDef[];

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

@@ -0,0 +1,187 @@
+import { z } from 'zod';
+import { Verified } from '@reticlehq/core';
+import { ReticleTool } from '../tools/tool-names.js';
+import { asNumber, asRecord, asString } from '../tools/tools-helpers.js';
+import { loadNamedFlows, resolveChangedFiles } from '../cli-flow-commands.js';
+import { affectedSavedFlows } from './flow-sources.js';
+import { FLOW_TOOLS } from './flow-tools.js';
+import { findContradictions } from '../events/contradictions.js';
+import { parseControls } from '../tools/coverage-tools.js';
+import { ReticleCommand, SnapshotMode } from '@reticlehq/core';
+const PASS = 'pass';
+export const VERIFY_CHANGE_TOOLS = [
+    {
+        name: ReticleTool.VERIFY_CHANGE,
+        description: 'Did my change break anything? Give it the files you edited (or `since` for a git ref) and it works out which saved flows cover them, replays exactly those, and answers with one `verified` (yes|no|unknown) plus `because`. `unknown` when NO saved flow covers the change — that is the honest answer, never a green: nothing ran, so nothing was proved. Returns { verified, because, changedFiles, flowsRun, suite, unknownProvenance }.',
+        example: { files: ['src/App.tsx'] },
+        inputSchema: {
+            files: z
+                .array(z.string())
+                .optional()
+                .describe('Changed file paths, repo-relative (e.g. ["src/App.tsx"]).'),
+            since: z
+                .string()
+                .optional()
+                .describe('Git ref to diff against (e.g. "HEAD~1", "main"). Unioned with `files`.'),
+            parallel: z
+                .number()
+                .optional()
+                .describe('Replay this many affected flows at once (needs the browser pool).'),
+            sessionId: z
+                .string()
+                .optional()
+                .describe('OMIT THIS unless you mean a specific tab — Reticle resolves it.'),
+        },
+        outputSchema: {
+            verified: z
+                .string()
+                .describe('yes | no | unknown. `unknown` means the evidence could not decide — most often that no saved flow covers these files, which is NOT a pass.'),
+            because: z.string(),
+            changedFiles: z.array(z.string()),
+            flowsRun: z.array(z.string()),
+            suite: z.unknown().optional(),
+            // Session-EXEMPT: declare the one-shot human feedback ask or a validating profile strips it.
+            feedback_prompt: z.unknown().optional(),
+            unknownProvenance: z.array(z.string()),
+            contradictions: z
+                .array(z.unknown())
+                .optional()
+                .describe('Channels that disagreed DURING the replay. Any entry forces verified:"no" even when every flow passed — a suite that goes green over a failed write is the false green this exists to catch. OMITTED when clean; see `measured` when it could not be looked for.'),
+            untouched: z
+                .array(z.unknown())
+                .optional()
+                .describe('Controls on the page that the covering flows never drove. A green over a small untouched list is stronger evidence than the same green over a large one.'),
+            measured: z
+                .array(z.string())
+                .describe('What was actually looked for. An absent `contradictions` means "none found" ONLY if "contradictions" appears here — otherwise it was never measured.'),
+        },
+        handler: async (deps, args) => {
+            const files = Array.isArray(args['files'])
+                ? args['files'].filter((f) => typeof f === 'string')
+                : [];
+            const since = asString(args['since']);
+            const changedFiles = await resolveChangedFiles(files, since);
+            const flows = await loadNamedFlows(deps.fs, deps.reticleRoot);
+            const { affected, unknownProvenance } = affectedSavedFlows(flows, changedFiles);
+            if (changedFiles.length === 0) {
+                return {
+                    verified: Verified.UNKNOWN,
+                    because: 'no changed files were given, so there was nothing to decide about',
+                    changedFiles,
+                    flowsRun: [],
+                    unknownProvenance,
+                    // Nothing was looked for, and the schema requires this field to say so. Omitting it made
+                    // the MCP layer reject the whole response, turning an honest UNKNOWN into a protocol error.
+                    measured: [],
+                };
+            }
+            // The guard: an uncovered change is UNKNOWN. Reporting `yes` here would mean "your change is
+            // fine" on the strength of having run nothing at all.
+            if (affected.length === 0) {
+                return {
+                    verified: Verified.UNKNOWN,
+                    because: `no saved flow covers ${changedFiles.length === 1 ? 'this file' : 'these files'} — record one with reticle_record { action: "start" } then reticle_flow_save, or verify by driving the app directly`,
+                    changedFiles,
+                    flowsRun: [],
+                    unknownProvenance,
+                    // No flow ran, so nothing was measured — said explicitly rather than left undefined.
+                    measured: [],
+                };
+            }
+            const provenanceNote = unknownProvenance.length > 0
+                ? ` (${String(unknownProvenance.length)} of them re-run only because Reticle cannot tell which sources they cover)`
+                : '';
+            // Marked BEFORE the replay so the contradiction sweep afterwards reads exactly the window the
+            // flows produced, and never events from whatever the agent did before calling this.
+            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');
+            const suite = asRecord(await verify.handler(deps, {
+                names: affected,
+                ...(asNumber(args['parallel']) === undefined ? {} : { parallel: args['parallel'] }),
+                ...(asString(args['sessionId']) === undefined ? {} : { sessionId: args['sessionId'] }),
+            }));
+            const failed = suite.failed ?? 0;
+            const passed = suite.passed ?? 0;
+            const failedSuite = suite.status !== PASS || failed > 0;
+            if (failedSuite) {
+                return {
+                    verified: Verified.NO,
+                    because: `${String(failed)} of ${String(suite.total ?? affected.length)} covering flows failed${provenanceNote}`,
+                    changedFiles,
+                    flowsRun: affected,
+                    suite,
+                    unknownProvenance,
+                    measured: ['flows'],
+                };
+            }
+            // The suite went green. That is exactly when the remaining two channels are worth reading:
+            // a replay that passes while a write fails is the false green this whole product is about.
+            const extra = await inspectAfterReplay(deps, args, cursor);
+            if (extra.contradictions.length > 0) {
+                const kinds = extra.contradictions.map((c) => c.kind).join(', ');
+                return {
+                    verified: Verified.NO,
+                    because: `every covering flow passed, but channels disagreed during the replay (${kinds}) — a green suite over a failed write is the false green worth looking at${provenanceNote}`,
+                    changedFiles,
+                    flowsRun: affected,
+                    suite,
+                    unknownProvenance,
+                    contradictions: extra.contradictions,
+                    ...(extra.untouched === undefined ? {} : { untouched: extra.untouched }),
+                    measured: extra.measured,
+                };
+            }
+            return {
+                verified: Verified.YES,
+                because: `all ${String(passed)} flows covering these files passed${provenanceNote}${extra.untouched === undefined ? '' : `, with ${String(extra.untouched.length)} controls left undriven`}`,
+                changedFiles,
+                flowsRun: affected,
+                suite,
+                unknownProvenance,
+                ...(extra.untouched === undefined ? {} : { untouched: extra.untouched }),
+                measured: extra.measured,
+            };
+        },
+    },
+];
+/** The event cursor to sweep from, or 0 when there is no readable session (nothing to sweep). */
+function cursorBeforeReplay(deps, args) {
+    try {
+        return deps.sessions.resolve(asString(args['sessionId'])).elapsed();
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Read the two channels a suite verdict cannot see: did anything DISAGREE during the replay, and
+ * what did the flows never touch.
+ *
+ * Both are skipped when the flows ran in parallel leased contexts, because the events and driven
+ * refs then belong to those leases rather than to the session read here. Reporting "no
+ * contradictions" from the wrong session would be a false green produced by the false-green
+ * detector, so `measured` states what was actually looked for and the caller is never left to infer
+ * it from an absent field.
+ */
+async function inspectAfterReplay(deps, args, cursor) {
+    if (asNumber(args['parallel']) !== undefined) {
+        return { contradictions: [], measured: ['flows'] };
+    }
+    try {
+        const session = deps.sessions.resolve(asString(args['sessionId']));
+        const contradictions = findContradictions(session.eventsSince(cursor));
+        const snapshot = await session.command(ReticleCommand.SNAPSHOT, {
+            mode: SnapshotMode.INTERACTIVE,
+        });
+        const tree = snapshot.ok ? (asString(asRecord(snapshot.result)['tree']) ?? '') : '';
+        const acted = session.actedRefs();
+        const untouched = parseControls(tree).filter((c) => !acted.has(c.ref));
+        return { contradictions, untouched, measured: ['flows', 'contradictions', 'coverage'] };
+    }
+    catch {
+        // A session that went away after the replay is not evidence of cleanliness.
+        return { contradictions: [], measured: ['flows'] };
+    }
+}

package/dist/flows/watch-batcher.d.ts

@@ -15,4 +15,3 @@ export interface WatchBatcherOptions {
     onFlush: (files: string[]) => void;
 }
 export declare function createWatchBatcher(options: WatchBatcherOptions): WatchBatcher;
-//# sourceMappingURL=watch-batcher.d.ts.map

package/dist/flows/watch-batcher.js

@@ -17,4 +17,3 @@ export function createWatchBatcher(options) {
         },
     };
 }
-//# sourceMappingURL=watch-batcher.js.map

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

@@ -0,0 +1,14 @@
+import { type ReticleEvent } from '@reticlehq/core';
+/**
+ * Did a write in this window answer `202 Accepted`?
+ *
+ * `202` is the only status in HTTP whose meaning is "no outcome yet" — the server took the request
+ * and has not finished with it. Folding it into the 2xx success band is how an asynchronous workflow
+ * gets a green verdict at exactly the moment nothing has been decided.
+ *
+ * Measured on a logistics console with server-side reconciliation: a dispatch answered 202, the row
+ * 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.
+ */
+export declare function hasAcceptedWrite(events: readonly ReticleEvent[]): boolean;

package/dist/honesty/accepted-write.js

@@ -0,0 +1,17 @@
+import { EventType, HTTP_ACCEPTED } from '@reticlehq/core';
+import { asNumber } from '../tools/tools-helpers.js';
+/**
+ * Did a write in this window answer `202 Accepted`?
+ *
+ * `202` is the only status in HTTP whose meaning is "no outcome yet" — the server took the request
+ * and has not finished with it. Folding it into the 2xx success band is how an asynchronous workflow
+ * gets a green verdict at exactly the moment nothing has been decided.
+ *
+ * Measured on a logistics console with server-side reconciliation: a dispatch answered 202, the row
+ * 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.
+ */
+export function hasAcceptedWrite(events) {
+    return events.some((e) => e.type === EventType.NET_REQUEST && asNumber(e.data['status']) === HTTP_ACCEPTED);
+}

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

@@ -16,6 +16,24 @@ export interface CoverageStatement {
     note?: string;
     spots: BlindSpot[];
 }
+/**
+ * Blind spots that IMPEACH the capture, as opposed to bounding what it covers.
+ *
+ * The distinction decides whether a verdict is downgraded to UNKNOWN or merely carries a caveat, and
+ * conflating them breaks the tool in one direction or the other:
+ *
+ *  - **Impeaching**: events were DROPPED, so the window itself is a sample and any claim over it may
+ *    be a false negative. Nothing observed can be trusted to be complete.
+ *  - **Bounding**: a region is structurally unobservable — a cross-origin frame, a closed shadow
+ *    root, the 9,970 virtualized rows that were never rendered. What WAS observed is completely and
+ *    correctly observed; there is simply a boundary, and it is usually permanent.
+ *
+ * Treating the second kind as impeaching made every verdict on any virtualized list UNKNOWN — which
+ * is most data-heavy software, permanently. A tool that answers "unknown" to everything is as
+ * useless as one that answers "yes" to everything, and it is the same failure: a verdict that does
+ * not depend on the evidence.
+ */
+export declare function impeachesCapture(kind: BlindSpotKind): boolean;
 /** Compose the coverage statement. `full` (no note) when nothing was unobserved. */
 export declare function buildCoverageStatement(spots: readonly BlindSpot[]): CoverageStatement;
 /**
@@ -34,4 +52,3 @@ export declare function blindSpotsFromEvents(events: readonly ReticleEvent[]): B
  * from what happened to be said recently.
  */
 export declare function blindSpotsFromState(state: Readonly<Record<string, number>>): BlindSpot[];
-//# sourceMappingURL=blind-spots.d.ts.map

package/dist/honesty/blind-spots.js

@@ -9,19 +9,62 @@
 export { BlindSpotKind } from '@reticlehq/core';
 import { BlindSpotKind, EventType } from '@reticlehq/core';
 const LABEL = {
-    [BlindSpotKind.CLOSED_SHADOW_ROOT]: (n) => `${String(n)} closed shadow root${n === 1 ? '' : 's'}`,
-    [BlindSpotKind.CROSS_ORIGIN_IFRAME]: (n) => `${String(n)} cross-origin frame${n === 1 ? '' : 's'}`,
-    [BlindSpotKind.VIRTUALIZED_UNMOUNTED]: (n) => `${String(n)} virtualized unmounted row${n === 1 ? '' : 's'}`,
+    [BlindSpotKind.CLOSED_SHADOW_ROOT]: (n) => `${String(n)} closed shadow root${n === 1 ? '' : 's'} unobserved`,
+    [BlindSpotKind.CROSS_ORIGIN_IFRAME]: (n) => `${String(n)} cross-origin frame${n === 1 ? '' : 's'} unobserved`,
+    // The DOM of these frames IS observed; only their network is not. Saying so precisely matters — a
+    // flat "unobserved" would discard a real capability and push agents back to guessing.
+    [BlindSpotKind.UNINSTRUMENTED_FRAME]: (n) => `${String(n)} same-origin frame${n === 1 ? '' : 's'} observed for DOM but not network — requests they make are invisible`,
+    [BlindSpotKind.VIRTUALIZED_UNMOUNTED]: (n) => `${String(n)} virtualized unmounted row${n === 1 ? '' : 's'} unobserved`,
+    // Not "some rows we could not see" — the events never reached the observer, so this window is a
+    // SAMPLE of what the app did. Phrased as a caveat on what the whole result MEANS.
+    [BlindSpotKind.RATE_LIMITED]: (n) => `${String(n)} event${n === 1 ? '' : 's'} dropped by the bridge rate cap, so this window is SAMPLED — raise RETICLE_MAX_MESSAGES_PER_SECOND for a busy app`,
     // Not a count of things — a single fact about the page. Phrased so the coverage line reads as a
     // caveat on what the network view MEANS, not as a tally.
+    // A count of unverifiable ACTIONS, not of things we failed to look at. The distinction matters:
+    // 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${n === 1 ? '' : 's'} dispatched with NO verdict — the renderer never learns whether the main process handled ${n === 1 ? 'it' : 'them'}, so this cannot be confirmed from the page`,
     [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
+    // the false green: every IPC call went unseen and every `assert { net }` over them is vacuous.
+    [BlindSpotKind.UNOBSERVED_IPC]: () => "this Electron renderer has no Reticle preload, so NO ipcRenderer.invoke is observed — an empty network view here means unseen, not none (add require('@reticlehq/electron/preload') to your preload)",
 };
+/**
+ * Blind spots that IMPEACH the capture, as opposed to bounding what it covers.
+ *
+ * The distinction decides whether a verdict is downgraded to UNKNOWN or merely carries a caveat, and
+ * conflating them breaks the tool in one direction or the other:
+ *
+ *  - **Impeaching**: events were DROPPED, so the window itself is a sample and any claim over it may
+ *    be a false negative. Nothing observed can be trusted to be complete.
+ *  - **Bounding**: a region is structurally unobservable — a cross-origin frame, a closed shadow
+ *    root, the 9,970 virtualized rows that were never rendered. What WAS observed is completely and
+ *    correctly observed; there is simply a boundary, and it is usually permanent.
+ *
+ * Treating the second kind as impeaching made every verdict on any virtualized list UNKNOWN — which
+ * is most data-heavy software, permanently. A tool that answers "unknown" to everything is as
+ * useless as one that answers "yes" to everything, and it is the same failure: a verdict that does
+ * not depend on the evidence.
+ */
+export function impeachesCapture(kind) {
+    return kind === BlindSpotKind.RATE_LIMITED;
+}
 /** Compose the coverage statement. `full` (no note) when nothing was unobserved. */
 export function buildCoverageStatement(spots) {
     const present = spots.filter((s) => s.count > 0);
     if (present.length === 0)
         return { coverage: 'full', spots: [] };
-    const note = `partial — ${present.map((s) => `${LABEL[s.kind](s.count)} unobserved`).join(', ')}`;
+    // Each label carries its own ending. Appending a blanket " unobserved" here produced
+    // "...may differ from what was sent unobserved" for the wrapped-network caveat, which is a
+    // sentence rather than a count — and the same dangle appeared the moment a second prose-shaped
+    // spot (rate-limited sampling) was added.
+    // A kind this daemon does not know about still has to READ as a blind spot. An SDK newer than the
+    // daemon can report one, and `LABEL[kind](count)` threw a TypeError on the verdict path when it
+    // did — turning "there is something I could not see" into a crashed assert, which is worse than
+    // either the caveat or the silence. Unknown kinds degrade to their own name.
+    const label = (s) => typeof LABEL[s.kind] === 'function' ? LABEL[s.kind](s.count) : `${s.kind} (${String(s.count)})`;
+    const note = `partial — ${present.map(label).join(', ')}`;
     return { coverage: 'partial', note, spots: present };
 }
 /**
@@ -54,4 +97,3 @@ export function blindSpotsFromEvents(events) {
 export function blindSpotsFromState(state) {
     return Object.entries(state).map(([kind, count]) => ({ kind: kind, count }));
 }
-//# sourceMappingURL=blind-spots.js.map

package/dist/honesty/honesty.d.ts

@@ -54,4 +54,3 @@ export declare function meetsHonestyBar(block: HonestyBlock, bar?: HonestyBar):
     ok: boolean;
     reasons: string[];
 };
-//# sourceMappingURL=honesty.d.ts.map

package/dist/honesty/honesty.js

@@ -60,4 +60,3 @@ export function meetsHonestyBar(block, bar = {}) {
     }
     return { ok: reasons.length === 0, reasons };
 }
-//# sourceMappingURL=honesty.js.map

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

@@ -0,0 +1,19 @@
+/**
+ * Say so when a payload exists but was not recorded.
+ *
+ * A `reticle_network` row for a POST lists method/url/status and nothing else, and an agent reading
+ * that has no way to tell "this request had no interesting payload" from "Reticle was not looking at
+ * payloads". The second reading is the dangerous one: on a real payments dashboard the defect WAS
+ * the payload — a refund POSTing `amount: 1187.01` into a paise field, a 100x under-refund that
+ * 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.
+ */
+export declare function bodiesNotCaptured(calls: {
+    method?: string;
+    requestBody?: string;
+}[]): {
+    bodiesNotCaptured?: string;
+};

package/dist/honesty/uncaptured-bodies.js

@@ -0,0 +1,30 @@
+/** Methods that normally carry a payload — the ones where a missing body is worth explaining. */
+const BODY_BEARING_METHODS = new Set(['POST', 'PUT', 'PATCH']);
+/**
+ * Say so when a payload exists but was not recorded.
+ *
+ * A `reticle_network` row for a POST lists method/url/status and nothing else, and an agent reading
+ * that has no way to tell "this request had no interesting payload" from "Reticle was not looking at
+ * payloads". The second reading is the dangerous one: on a real payments dashboard the defect WAS
+ * the payload — a refund POSTing `amount: 1187.01` into a paise field, a 100x under-refund that
+ * 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.
+ */
+export function bodiesNotCaptured(calls) {
+    const bodyBearing = calls.filter((c) => BODY_BEARING_METHODS.has((c.method ?? '').toUpperCase()));
+    if (bodyBearing.length === 0)
+        return {};
+    if (bodyBearing.some((c) => c.requestBody !== undefined))
+        return {};
+    return {
+        // Framework-neutral on purpose. The first version named vite.config, and driving a Next.js app
+        // returned that advice verbatim for a SERVER ACTION — a POST a Next user cannot fix in a Vite
+        // config they do not have. Remediation that does not apply to the reader's stack is worse than
+        // none: it sends them to edit a file that is not there and reads as a tool that does not know
+        // what it is looking at.
+        bodiesNotCaptured: 'request/response bodies are NOT being recorded, so an absent body here means UNSEEN, not empty — the payload of these calls was never inspected. 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.',
+    };
+}

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

@@ -0,0 +1,2 @@
+import { type ReticleEvent } from '@reticlehq/core';
+export declare function hasUnreadWriteOutcome(events: readonly ReticleEvent[]): boolean;

package/dist/honesty/unread-outcome.js

@@ -0,0 +1,50 @@
+import { EventType, MUTATING_METHODS, NetInitiator } from '@reticlehq/core';
+const IPC_METHOD = NetInitiator.IPC.toUpperCase();
+/**
+ * A write whose outcome is sitting in a payload nobody read.
+ *
+ * `findBodyFailures` catches a 2xx that reports failure inside its body — but only when body capture
+ * is on, and it is OFF by default. Without this, the same window produces `verified: "yes"` with the
+ * reason "no channel disagreeing", which is true only because one channel was never opened. That is
+ * lying by omission, and it is the precise failure this honesty layer exists to prevent.
+ *
+ * Measured on a shipments console: `POST /api/bulk-hold` → 200, banner reads "9 shipments held",
+ * three of the nine failed inside the body. With capture on Reticle now says so. With capture off it
+ * said `verified: "yes"`.
+ *
+ * Deliberately narrow, because over-warning trains agents to ignore the field:
+ *
+ *  - **writes only.** A GET's payload is what the UI renders, so the DOM already witnesses it. A
+ *    write's outcome has no other witness.
+ *  - **a payload that DEMONSTRABLY exists.** `responseSize > 0` with no recorded body means unread.
+ *    An absent size or a genuinely empty response says nothing and is left alone — the distinction
+ *    between "empty" and "unseen" is the whole point, so it must not be guessed.
+ *  - **HTTP only.** An IPC record is excluded, and the reason is the rule's own premise: a 2xx is
+ *    emitted by a framework whatever the app decided, so it describes the transport. An IPC `ok`
+ *    means the main-process handler ran to completion without throwing — an application-level
+ *    verdict, already reported. Treating the two as equivalent made every ordinary Electron action
+ *    return `unknown` (measured: a healthy `todos:add` on the default config), which is the
+ *    cry-wolf failure that teaches agents to ignore the field.
+ *
+ *    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.
+ */
+const OK_MIN = 200;
+const OK_MAX = 300;
+export function hasUnreadWriteOutcome(events) {
+    return events.some((event) => {
+        if (event.type !== EventType.NET_REQUEST)
+            return false;
+        const method = (typeof event.data['method'] === 'string' ? event.data['method'] : '').toUpperCase();
+        if (method === IPC_METHOD || !MUTATING_METHODS.includes(method))
+            return false;
+        const status = event.data['status'];
+        if (typeof status !== 'number' || status < OK_MIN || status >= OK_MAX)
+            return false;
+        if (event.data['responseBody'] !== undefined)
+            return false; // read — findBodyFailures judged it
+        const size = event.data['responseSize'];
+        return typeof size === 'number' && size > 0;
+    });
+}