@reticlehq/server 2.2.1 → 2.3.0

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;
+    });
+}

package/dist/honesty/verified.d.ts

@@ -0,0 +1,40 @@
+import { Verified } from '@reticlehq/core';
+import { type HonestyBlock } from './honesty.js';
+/**
+ * The decision rule: eight trust dimensions in, one answer out.
+ *
+ * Everything needed to judge an action already travelled on the result — the assertion verdict, the
+ * grade it proved, whether the capture was clean, whether the page settled, whether any channel
+ * disagreed. What was missing was the RULE, so every agent had to invent one, and inventing it under
+ * uncertainty is exactly where a confident wrong answer comes from.
+ *
+ * Ordering is deliberate, because the first matching clause also writes `because`, and the reader
+ * should be told the most actionable fact rather than the first true one.
+ */
+export interface VerifiedInputs {
+    /** Did the declared consequence hold? Undefined when the action declared none. */
+    pass?: boolean;
+    honesty: HonestyBlock;
+    /** Cross-channel disagreements found in the action's window. */
+    contradictions?: readonly {
+        kind: string;
+    }[];
+    /** Did a real frame flush before the wait gave up? */
+    settled?: boolean;
+    /**
+     * A write in this window answered `202 Accepted` — the server took the request and has NOT
+     * finished processing it.
+     */
+    outcomePending?: boolean;
+    /**
+     * A write in this window returned 2xx with a payload that was never recorded, so its outcome was
+     * never read. See `hasUnreadWriteOutcome` — the status line describes the transport, not the result.
+     */
+    outcomeUnread?: boolean;
+}
+export interface VerifiedVerdict {
+    verified: Verified;
+    /** One sentence naming the deciding evidence — never a restatement of the field. */
+    because: string;
+}
+export declare function decideVerified(inputs: VerifiedInputs): VerifiedVerdict;

package/dist/honesty/verified.js

@@ -0,0 +1,86 @@
+import { Verified } from '@reticlehq/core';
+import { HonestyGrade } from './honesty.js';
+export function decideVerified(inputs) {
+    const { pass, honesty, contradictions = [], settled, outcomePending, outcomeUnread } = inputs;
+    // A failed assertion is the most actionable fact there is; it leads.
+    if (pass === false) {
+        return { verified: Verified.NO, because: 'the declared consequence did not hold' };
+    }
+    // A contradiction outranks a passing assertion, and that inversion is the whole point: the case
+    // this product exists to catch is a green assertion sitting on top of a failed write. Measured on
+    // the bench app — `ui-advanced-request-failed` arrived with verdict.pass true and every other
+    // channel agreeing. Letting `pass` win there would report exactly the false green being detected.
+    if (contradictions.length > 0) {
+        const kinds = contradictions.map((c) => c.kind).join(', ');
+        return {
+            verified: Verified.NO,
+            because: `channels disagree about this action (${kinds}) even though the assertion passed`,
+        };
+    }
+    // Dirty capture is NOT failure. The layer could not see part of the window, so any green is a
+    // statement about what it happened to observe — which is precisely the thing that must not be
+    // reported as proof.
+    if (!honesty.integrity.clean) {
+        return {
+            verified: Verified.UNKNOWN,
+            because: `capture was not clean (${honesty.integrity.issues.join('; ')}), so a green here would only describe what was observed`,
+        };
+    }
+    // A vacuous green: nothing was actually proved. Grade NONE means no signal, no request, no state
+    // change and no element was pinned — the assertion could not have failed, which makes passing it
+    // evidence of nothing.
+    if (honesty.grade === HonestyGrade.NONE) {
+        return {
+            verified: Verified.UNKNOWN,
+            because: 'nothing was asserted at a real grade, so passing proves nothing — assert a signal, request, or state path',
+        };
+    }
+    // A `202 Accepted` is the server saying, in the only word HTTP has for it, that the outcome does
+    // not exist yet. Treating 2xx as success makes every asynchronous workflow verifiable 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, and the verdict came back `yes` — then
+    // the server REVERTED it to `held` 1.2s later. Every channel agreed, and every channel was early.
+    // UNKNOWN rather than NO: nothing has failed, and saying it has would be its own false report.
+    if (outcomePending === true) {
+        return {
+            verified: Verified.UNKNOWN,
+            because: 'a write returned 202 Accepted, so the server has not finished processing it — this window cannot contain the outcome; re-check once it reconciles',
+        };
+    }
+    // A write answered 2xx and its payload went unread, so the one channel that could contradict the
+    // screen was never opened. Reporting `yes` here means "no channel disagreed" — true only because a
+    // channel was closed. Measured on a shipments console: `POST /api/bulk-hold` → 200 with three of
+    // nine items failed inside the body, banner reading "9 shipments held", verdict `yes`.
+    //
+    // UNKNOWN, not NO: nothing is known to have failed. The remedy is in the sentence, because an
+    // agent that cannot act on a caveat will learn to skip it.
+    if (outcomeUnread === true) {
+        return {
+            verified: Verified.UNKNOWN,
+            because: 'a write returned 2xx with a response body that was never recorded, so its outcome is unread — a 200 describes the transport, not the result (a batch reports per-item failures in the body, and every GraphQL error is a 200). Enable it where your app calls connect(): `reticle.connect({ captureNetworkBodies: true })`, then re-run',
+        };
+    }
+    // Never settled: the page may still be moving, so the observation window may have closed early.
+    if (settled === false) {
+        return {
+            verified: Verified.UNKNOWN,
+            because: 'the page never settled, so the reaction window may have closed before the app finished',
+        };
+    }
+    // Partial coverage is a real caveat but not a blocker — it is reported in `honesty.coverage` and
+    // does not by itself make a graded, clean, uncontradicted pass untrustworthy.
+    //
+    // It must not be described as clean, though. This sentence said "over a clean capture" regardless,
+    // so a verdict could read `verified: yes ... over a clean capture` directly beside `coverage:
+    // partial` — the prose contradicting the evidence block next to it. Whichever a reader believes,
+    // one of them lied, and the whole point of this layer is that the sentence can be trusted on its
+    // own. Seen on a one-way IPC send: coverage said the outcome was unobservable, `because` said clean.
+    return {
+        verified: Verified.YES,
+        because: honesty.coverage?.partial === true
+            ? `assertion held at ${honesty.grade} grade with no channel disagreeing, but coverage was PARTIAL — see \`coverage\` for what went unobserved`
+            : `assertion held at ${honesty.grade} grade over a clean capture with no channel disagreeing`,
+    };
+}

package/dist/http-server.d.ts

@@ -32,4 +32,3 @@ export interface SharedServer {
 export declare function createSharedServer(options?: {
     token?: string;
 }): SharedServer;
-//# sourceMappingURL=http-server.d.ts.map

package/dist/http-server.js

@@ -2,6 +2,7 @@ import * as http from 'node:http';
 import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
 import { MCP_SSE_PATH, MCP_MESSAGE_PATH, STATUS_PATH } from '@reticlehq/core';
 import { log } from './log.js';
+import { reportMcpConnected } from './telemetry/mcp-connection.js';
 import { isLoopbackHost, isLocalWebOrigin, isLoopbackPeer, requestToken, tokensMatch, } from './token-auth.js';
 /**
  * Creates a shared HTTP server that handles both the WebSocket bridge (browser SDK) and the
@@ -84,6 +85,10 @@ export function createSharedServer(options = {}) {
                 .connect(transport)
                 .then(() => {
                 log('mcp_client_connected', { sessionId: sid });
+                // The one signal that separates "Reticle is running" from "somebody is USING it": a daemon
+                // can sit up for days with nothing attached. It also exposes reconnect churn, which is
+                // indistinguishable from healthy usage in every other metric.
+                reportMcpConnected();
             })
                 .catch((err) => {
                 const message = err instanceof Error ? err.message : String(err);
@@ -138,4 +143,3 @@ export function createSharedServer(options = {}) {
     }
     return { httpServer, attachMcp, attachStatus, attachAgentPresence, close };
 }
-//# sourceMappingURL=http-server.js.map