@reticlehq/server 2.5.0 → 2.7.0

package/dist/events/ring-buffer.js

@@ -1,19 +1,4 @@
-import { EventType, RING_BUFFER_DEFAULTS } from '@reticlehq/core';
-/**
- * The high-volume, low-signal floor. These fire continuously on any live page (count-up text, CSS
- * animation frames, React commits, health heartbeats, scroll) and are the ONLY thing that should be
- * sacrificed when the buffer is full. Everything else — a failed request, a console error, a domain
- * signal, a truncation/blind-spot marker — is scarce evidence a verdict depends on, and a churning
- * region must never be able to push it out of the window.
- */
-const CHURN_TYPES = new Set([
-    EventType.DOM_TEXT,
-    EventType.ANIM_START,
-    EventType.ANIM_END,
-    EventType.RENDER_COMMIT,
-    EventType.PAGE_HEALTH,
-    EventType.SCROLL_POSITION,
-]);
+import { CHURN_TYPES, RING_BUFFER_DEFAULTS } from '@reticlehq/core';
 /** How far forward to look for a churn event to sacrifice before falling back to plain FIFO. */
 const CHURN_SCAN_LIMIT = 256;
 /**
@@ -38,6 +23,16 @@ export class RingBuffer {
     #head = 0;
     #totalBytes = 0;
     #droppedCount = 0;
+    /**
+     * The timestamp of the newest NON-CHURN event this buffer has ever evicted, or `undefined` if it
+     * has never lost one. This — not the drop counter — is what impeaches an observation window.
+     *
+     * The counter cannot answer the question. It moves for age eviction (everything past 60s, on every
+     * push) and for churn eviction (the low-signal floor, sacrificed on purpose so scarce evidence
+     * survives), neither of which is evidence lost from the window an agent just observed. See
+     * `lostSince` and `ring-buffer-window-loss.test.ts`.
+     */
+    #lastScarceLossT;
     constructor(options = {}) {
         this.#maxEvents = options.maxEvents ?? RING_BUFFER_DEFAULTS.MAX_EVENTS;
         this.#maxAgeMs = options.maxAgeMs ?? RING_BUFFER_DEFAULTS.MAX_AGE_MS;
@@ -96,7 +91,10 @@ export class RingBuffer {
             }
             const victim = this.#findChurnAfterHead();
             if (-1 === victim) {
-                // Buffer genuinely full of high-signal events — fall back to FIFO so it stays bounded.
+                // Buffer genuinely full of high-signal events — fall back to FIFO so it stays bounded. This
+                // is the one eviction path that destroys scarce evidence, and the only one that should ever
+                // make a verdict say it could not see.
+                this.#noteScarceLoss(this.#head);
                 this.#totalBytes -= this.#eventBytes[this.#head] ?? 0;
                 this.#head += 1;
                 continue;
@@ -106,6 +104,7 @@ export class RingBuffer {
             this.#eventBytes.splice(victim, 1);
         }
         while (this.#liveCount() > 0 && (this.#events[this.#head]?.t ?? cutoff) < cutoff) {
+            this.#noteScarceLoss(this.#head);
             this.#totalBytes -= this.#eventBytes[this.#head] ?? 0;
             this.#head += 1;
         }
@@ -117,6 +116,25 @@ export class RingBuffer {
             this.#head = 0;
         }
     }
+    /** Record an eviction at `index` as scarce loss, unless it was the churn floor being sacrificed. */
+    #noteScarceLoss(index) {
+        const victim = this.#events[index];
+        if (victim === undefined || CHURN_TYPES.has(victim.type))
+            return;
+        if (this.#lastScarceLossT === undefined || victim.t > this.#lastScarceLossT) {
+            this.#lastScarceLossT = victim.t;
+        }
+    }
+    /**
+     * Did this buffer evict scarce evidence that belonged to a window opened at `cursor`?
+     *
+     * The one honest input to "was the capture clean". A `false` here means every non-churn event in
+     * the window is still held, whatever the drop counter says — and the drop counter says a great
+     * deal, because age eviction runs on every push.
+     */
+    lostSince(cursor) {
+        return this.#lastScarceLossT !== undefined && this.#lastScarceLossT >= cursor;
+    }
     /** First churn event after the head, or -1 if none within the bounded scan (keeps eviction cheap). */
     #findChurnAfterHead() {
         const end = Math.min(this.#events.length, this.#head + CHURN_SCAN_LIMIT);

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

@@ -49,7 +49,7 @@ export type Sleep = (ms: number) => Promise<void>;
 export declare function nearestIsAmbiguous(missing: string, present: string[]): boolean;
 /** Build the legible-drift record for a testid anchor that resolved to zero live elements. */
 export declare function testidDrift(value: string, hint: QueryEmptyHint | undefined): Drift;
-export declare function resolveQuery(session: FlowReplaySession, queryArgs: Record<string, unknown>, sleep: Sleep): Promise<{
+export declare function resolveQuery(session: FlowReplaySession, queryArgs: Record<string, unknown>, sleep: Sleep, now?: () => number): Promise<{
     refs: string[];
     hint?: QueryEmptyHint;
 }>;

package/dist/flows/flow-replay.js

@@ -61,6 +61,22 @@ export function nearestTestid(missing, present) {
  */
 const ANCHOR_SETTLE_ATTEMPTS = 8;
 const ANCHOR_SETTLE_DELAY_MS = 150;
+/**
+ * The budget that actually governs, in wall-clock milliseconds.
+ *
+ * Attempts were the bound, and on an event-chatty page that collapsed. `settleTick` ends on EITHER
+ * an event OR the tick, so a page emitting continuously (API calls, a large form render, CSS
+ * transition start/end pairs) burned all eight attempts in **224–758ms measured** — a budget
+ * documented as 1.2s, spent in a fifth of it, before a newly routed page had mounted its controls.
+ * Cross-route replays drifted `testid_not_found` at 278ms while the same flow passed on a quiet page.
+ *
+ * An event arriving is evidence the page is still working. It should EXTEND the wait, not spend it.
+ * So the deadline decides when to give up, and the attempt cap below survives only as a backstop
+ * against a pathological storm spinning this loop hot.
+ */
+const ANCHOR_SETTLE_BUDGET_MS = ANCHOR_SETTLE_ATTEMPTS * ANCHOR_SETTLE_DELAY_MS;
+/** Backstop only. Generous on purpose: the deadline is the real bound, this just prevents a spin. */
+const ANCHOR_SETTLE_MAX_ATTEMPTS = 40;
 const realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /** Extract the live element refs + the zero-match near-miss hint from a QUERY command result. */
 function readQuery(result) {
@@ -158,9 +174,10 @@ async function settleTick(session, sleep) {
         unsubscribe?.();
     }
 }
-export async function resolveQuery(session, queryArgs, sleep) {
+export async function resolveQuery(session, queryArgs, sleep, now = Date.now) {
     let last = readQuery(await session.command(ReticleCommand.QUERY, queryArgs));
-    for (let attempt = 1; 0 === last.refs.length && attempt < ANCHOR_SETTLE_ATTEMPTS; attempt += 1) {
+    const deadline = now() + ANCHOR_SETTLE_BUDGET_MS;
+    for (let attempt = 1; 0 === last.refs.length && now() < deadline && attempt < ANCHOR_SETTLE_MAX_ATTEMPTS; attempt += 1) {
         await settleTick(session, sleep);
         last = readQuery(await session.command(ReticleCommand.QUERY, queryArgs));
     }

package/dist/flows/flow-step-runners.js

@@ -11,6 +11,7 @@ import { ReticleTool } from '../tools/tool-names.js';
 import { replayActionArgs } from './replay.js';
 import { anchorLabel, componentLabel, componentQueryArgs, resolveQuery, testidDrift, } from './flow-replay.js';
 import { nearestRoleName } from './role-anchor-nearest.js';
+import { roleDriftReason } from './role-drift-reason.js';
 /** Query args for a NAMED role anchor — the handle that identifies an instance, not a JSX site. */
 function roleQueryArgs(anchor) {
     return {
@@ -74,9 +75,7 @@ export async function runRoleStep(session, step, index, anchor, confirmDangerous
             ok: false,
             drift: {
                 reasonKind: DriftReason.COMPONENT_NOT_FOUND,
-                reason: null === nearest
-                    ? `role anchor ${label} not found, and no surviving ${anchor.role} has a similar name — anchor this step to a data-testid`
-                    : `role anchor ${label} not found; the closest surviving ${anchor.role} is "${nearest}" — confirm it is the same control before rebinding, or add a data-testid`,
+                reason: roleDriftReason(anchor.role, String(anchor.name), nearest),
                 anchor: label,
                 nearest,
             },

package/dist/flows/flow-tools.js

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { emptyFlowRefusal } from './empty-flow.js';
 import { aliasParam } from '../tools/alias-args.js';
 import { FlowErrorCode, RecordedSaveError, ReplayStatus, } from '@reticlehq/core';
-import { FlakeStore } from './flake-store.js';
+import { recordSuiteFlakes } from './suite-flakes.js';
 import { ReticleTool } from '../tools/tool-names.js';
 import { asNumber, asString } from '../tools/tools-helpers.js';
 import { log } from '../log.js';
@@ -383,18 +383,15 @@ export const FLOW_TOOLS = [
                     const flow = loaded !== null && loaded.ok ? loaded.value : undefined;
                     return flow === undefined ? { replay } : { replay, flow };
                 }));
-                return buildSuiteVerdict(parallelRuns);
+                const flaky = await recordSuiteFlakes(deps.fs, deps.reticleRoot, parallelRuns);
+                const verdict = buildSuiteVerdict(parallelRuns);
+                return flaky.length > 0 ? { ...verdict, flaky: [...flaky] } : verdict;
             }
             // The flow FILE travels with each replay so the verdict can tell a green that verified
             // something from a green that could never have gone red. Without it the suite reported "all 1
             // flow pass" for a flow with no steps at all.
             const runs = [];
             const timed = [];
-            // The flake ledger the CLI gate already keeps — see FlakeStore. It was only ever written by
-            // `reticle flow` on the command line, so an AGENT running this tool a hundred times learned
-            // nothing about which flows are intermittent. Same product, same ledger, two surfaces, and the
-            // one an agent uses was the blind half.
-            const flakes = new FlakeStore(deps.fs, deps.reticleRoot);
             // Sequential default: every flow replays against the same live session, so they must not overlap.
             for (const flowName of requested) {
                 const start = deps.now();
@@ -404,19 +401,18 @@ export const FLOW_TOOLS = [
                 runs.push(flow === undefined ? { replay } : { replay, flow });
                 timed.push({ replay, durationMs: deps.now() - start });
             }
-            // Accrue this run's outcomes, then report what the ledger knows. Best-effort on both halves: a
-            // flake ledger is memory, not a gate, and it must never turn a working verify into an error.
-            for (const { replay } of runs) {
-                await flakes.record(replay.name, replay.status === ReplayStatus.OK).catch(() => undefined);
-            }
-            const flaky = await flakes.flakyFlows().catch(() => []);
+            // The flake ledger the CLI gate already keeps — see FlakeStore. It was only ever written by
+            // `reticle flow` on the command line, so an AGENT running this tool a hundred times learned
+            // nothing about which flows are intermittent. Same product, same ledger, two surfaces, and the
+            // one an agent uses was the blind half.
+            const flaky = await recordSuiteFlakes(deps.fs, deps.reticleRoot, runs);
             // Emit the consolidated run artifact (Runs tab) + best-effort cloud push. Never blocks the verdict.
             await persistAndSyncVerificationRun(deps, timed, projectId);
             const verdict = buildSuiteVerdict(runs);
             // A flow that has both passed and failed on UNCHANGED code is a different thing from a
             // regression, and an agent that cannot tell them apart either chases a ghost or ignores a real
             // break. Present only when the ledger has seen enough runs to say so.
-            return flaky.length > 0 ? { ...verdict, flaky } : verdict;
+            return flaky.length > 0 ? { ...verdict, flaky: [...flaky] } : verdict;
         },
     },
     {

package/dist/flows/role-drift-reason.d.ts

@@ -0,0 +1,20 @@
+/**
+ * What to say when a role+name anchor no longer resolves.
+ *
+ * The old message could contradict itself in the one case that matters most:
+ *
+ *   role anchor button "Add User" not found; the closest surviving button is "Add User"
+ *
+ * Read literally that says the control both is and is not there, and it cost a reporter real
+ * debugging time. What it means is more useful than a rename: the stored name and the live
+ * accessible name are the SAME STRING, so the name is not what changed — the query matched nothing
+ * for some other reason.
+ *
+ * In the reported case the recorded name came from a `placeholder` — `reticle_query` reports
+ * `name:"Search User"` for `<input type="search" placeholder="Search User">` with no label — and the
+ * replay resolver computes accessible names differently, so the round trip cannot close. That is a
+ * real bug in its own right (two accessible-name implementations disagreeing), and while it is open
+ * the message is the only thing the reader has, because `flow_heal` correctly refuses to rebind a
+ * role anchor on its own.
+ */
+export declare function roleDriftReason(role: string, name: string, nearest: string | null): string;

package/dist/flows/role-drift-reason.js

@@ -0,0 +1,39 @@
+/**
+ * What to say when a role+name anchor no longer resolves.
+ *
+ * The old message could contradict itself in the one case that matters most:
+ *
+ *   role anchor button "Add User" not found; the closest surviving button is "Add User"
+ *
+ * Read literally that says the control both is and is not there, and it cost a reporter real
+ * debugging time. What it means is more useful than a rename: the stored name and the live
+ * accessible name are the SAME STRING, so the name is not what changed — the query matched nothing
+ * for some other reason.
+ *
+ * In the reported case the recorded name came from a `placeholder` — `reticle_query` reports
+ * `name:"Search User"` for `<input type="search" placeholder="Search User">` with no label — and the
+ * replay resolver computes accessible names differently, so the round trip cannot close. That is a
+ * real bug in its own right (two accessible-name implementations disagreeing), and while it is open
+ * the message is the only thing the reader has, because `flow_heal` correctly refuses to rebind a
+ * role anchor on its own.
+ */
+/** Same name to a reader: case and surrounding whitespace are not a rename. */
+function sameName(a, b) {
+    return a.trim().toLowerCase() === b.trim().toLowerCase();
+}
+export function roleDriftReason(role, name, nearest) {
+    const label = `${role} "${name}"`;
+    if (null === nearest) {
+        return (`role anchor ${label} not found, and no surviving ${role} has a similar name — ` +
+            'anchor this step to a data-testid');
+    }
+    if (sameName(name, nearest)) {
+        // The one case the old wording made unreadable. Say what is ruled OUT — that is the information.
+        return (`role anchor ${label} did not resolve, but a ${role} with an identical name is on the page — ` +
+            'so this is NOT a rename and editing the label will not fix it. The recorded name and the ' +
+            'name the resolver computes disagree, which happens when the recorded one came from a ' +
+            'placeholder or title rather than a label or aria-label. Anchor this step to a data-testid.');
+    }
+    return (`role anchor ${label} not found; the closest surviving ${role} is "${nearest}" — ` +
+        'confirm it is the same control before rebinding, or add a data-testid');
+}

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

@@ -0,0 +1,33 @@
+/**
+ * Accrue a suite run's outcomes into the flake ledger, and report what the ledger knows.
+ *
+ * This existed twice — once in `flow_verify`'s sequential branch and once, after #240, in its
+ * parallel branch. That duplication is not incidental: the parallel branch shipped WITHOUT it, so an
+ * agent verifying in parallel built no flake evidence at all and never saw the quarantine set, and
+ * nothing went red because the other copy was still correct. One function both branches call is what
+ * makes that miss impossible on one side only.
+ *
+ * It is also what makes the behaviour testable. The handler itself needs a live browser session, so
+ * both branches were only ever pinned by tests that RE-IMPLEMENTED this loop — which passed with the
+ * shipped code reverted (measured on #240: 4/4 green with the fix absent). Extracted, the real thing
+ * runs in a unit test.
+ *
+ * Best-effort on both halves, deliberately: a flake ledger is memory, not a gate. A full disk must
+ * never turn a working verification into an error.
+ */
+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 {
+    readonly name: string;
+    readonly status: ReplayStatus;
+}
+/**
+ * Record every outcome, then ask which flows are intermittent.
+ *
+ * Anything that is not `OK` — `ERROR` or `DRIFT` — counts as a failure for the ledger. That is the
+ * rule both call sites already used, preserved rather than chosen here.
+ */
+export declare function recordSuiteFlakes(fs: FileSystemPort, reticleRoot: string, runs: readonly {
+    readonly replay: FlakeOutcome;
+}[]): Promise<readonly string[]>;

package/dist/flows/suite-flakes.js

@@ -0,0 +1,32 @@
+/**
+ * Accrue a suite run's outcomes into the flake ledger, and report what the ledger knows.
+ *
+ * This existed twice — once in `flow_verify`'s sequential branch and once, after #240, in its
+ * parallel branch. That duplication is not incidental: the parallel branch shipped WITHOUT it, so an
+ * agent verifying in parallel built no flake evidence at all and never saw the quarantine set, and
+ * nothing went red because the other copy was still correct. One function both branches call is what
+ * makes that miss impossible on one side only.
+ *
+ * It is also what makes the behaviour testable. The handler itself needs a live browser session, so
+ * both branches were only ever pinned by tests that RE-IMPLEMENTED this loop — which passed with the
+ * shipped code reverted (measured on #240: 4/4 green with the fix absent). Extracted, the real thing
+ * runs in a unit test.
+ *
+ * Best-effort on both halves, deliberately: a flake ledger is memory, not a gate. A full disk must
+ * never turn a working verification into an error.
+ */
+import { ReplayStatus } from '@reticlehq/core';
+import { FlakeStore } from './flake-store.js';
+/**
+ * Record every outcome, then ask which flows are intermittent.
+ *
+ * Anything that is not `OK` — `ERROR` or `DRIFT` — counts as a failure for the ledger. That is the
+ * rule both call sites already used, preserved rather than chosen here.
+ */
+export async function recordSuiteFlakes(fs, reticleRoot, runs) {
+    const flakes = new FlakeStore(fs, reticleRoot);
+    for (const { replay } of runs) {
+        await flakes.record(replay.name, ReplayStatus.OK === replay.status).catch(() => undefined);
+    }
+    return flakes.flakyFlows().catch(() => []);
+}

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

@@ -65,3 +65,22 @@ 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[];
+/**
+ * Events the BROWSER's own transport queue threw away inside this window, or 0.
+ *
+ * `RATE_LIMITED` — the BRIDGE sampling because events arrived faster than its per-second cap — is
+ * already the one blind spot that `impeachesCapture`, on the reasoning that a green over a window
+ * you did not fully see "would only describe what was observed". `TRANSPORT_OVERFLOW` is the exact
+ * same loss on the other side of the wire, and it was read in journal rollups and NOWHERE on the
+ * verdict path. So the identical condition downgraded a verdict from one side of the socket and was
+ * invisible from the other: a window that dropped 34 events graded `proved`, in a sentence whose own
+ * words were "over a clean capture".
+ *
+ * `TRUNCATED` is deliberately NOT counted. It names the channel it capped (a DOM-mutation flood on
+ * any busy page) and is routine churn; treating it as lost evidence would caveat every verdict on
+ * every real app, and a caveat that is always present is one nobody reads. TRANSPORT_OVERFLOW is the
+ * honest "arbitrary events are gone" marker — it cannot say which.
+ */
+export declare function droppedByTransport(events: readonly ReticleEvent[]): number;
+/** The impeaching note for a transport gap, or undefined when the window was intact. */
+export declare function transportGapNote(events: readonly ReticleEvent[]): string | undefined;

package/dist/honesty/blind-spots.js

@@ -109,3 +109,36 @@ export function blindSpotsFromEvents(events) {
 export function blindSpotsFromState(state) {
     return Object.entries(state).map(([kind, count]) => ({ kind: kind, count }));
 }
+/**
+ * Events the BROWSER's own transport queue threw away inside this window, or 0.
+ *
+ * `RATE_LIMITED` — the BRIDGE sampling because events arrived faster than its per-second cap — is
+ * already the one blind spot that `impeachesCapture`, on the reasoning that a green over a window
+ * you did not fully see "would only describe what was observed". `TRANSPORT_OVERFLOW` is the exact
+ * same loss on the other side of the wire, and it was read in journal rollups and NOWHERE on the
+ * verdict path. So the identical condition downgraded a verdict from one side of the socket and was
+ * invisible from the other: a window that dropped 34 events graded `proved`, in a sentence whose own
+ * words were "over a clean capture".
+ *
+ * `TRUNCATED` is deliberately NOT counted. It names the channel it capped (a DOM-mutation flood on
+ * any busy page) and is routine churn; treating it as lost evidence would caveat every verdict on
+ * every real app, and a caveat that is always present is one nobody reads. TRANSPORT_OVERFLOW is the
+ * honest "arbitrary events are gone" marker — it cannot say which.
+ */
+export function droppedByTransport(events) {
+    let dropped = 0;
+    for (const e of events) {
+        if (e.type !== EventType.TRANSPORT_OVERFLOW)
+            continue;
+        const n = e.data['dropped'];
+        dropped += 'number' === typeof n ? n : 0;
+    }
+    return dropped;
+}
+/** The impeaching note for a transport gap, or undefined when the window was intact. */
+export function transportGapNote(events) {
+    const dropped = droppedByTransport(events);
+    return 0 === dropped
+        ? undefined
+        : `the browser dropped ${String(dropped)} event(s) in this window (transport queue overflow), so events that would have contradicted this may never have arrived`;
+}

package/dist/honesty/honesty.d.ts

@@ -5,6 +5,7 @@
  * block. Harnesses gate on it (e.g. "grade ≥ net AND integrity clean"). This is pure composition +
  * assessment — all five components already exist individually; wiring it onto results is a later step.
  */
+import type { CaptureLoss } from '@reticlehq/core';
 /** Assertion grade, strongest first — the tier the verdict actually proved. */
 export declare const HonestyGrade: {
     readonly SIGNAL: "signal";
@@ -23,6 +24,15 @@ interface HonestyInputs {
     coveragePartial?: boolean;
     truncated?: boolean;
     blindSpots?: readonly string[];
+    /**
+     * The machine-readable half of `issues` — WHICH kind of loss, from core's closed `CaptureLoss`.
+     *
+     * `issues` is prose built for an agent to read, and prose is not something a dashboard can group
+     * by: `unclean_capture` became a large share of all field verdicts with no way to ask which of its three
+     * causes produced them. Passed by the caller rather than derived here, because only the caller
+     * knows whether a blind-spot note came from the browser transport or from a boundary in the page.
+     */
+    losses?: readonly CaptureLoss[];
 }
 export interface HonestyBlock {
     grade: HonestyGrade;
@@ -40,6 +50,7 @@ export interface HonestyBlock {
     integrity: {
         clean: boolean;
         issues: string[];
+        losses?: CaptureLoss[];
     };
 }
 export declare function buildHonestyBlock(inputs: HonestyInputs): HonestyBlock;

package/dist/honesty/honesty.js

@@ -46,7 +46,15 @@ export function buildHonestyBlock(inputs) {
             ? {}
             : { envelope: { samples, sufficient: samples >= MIN_ENVELOPE_SAMPLES } }),
         coverage: { ...(pct === undefined ? {} : { pct }), partial },
-        integrity: { clean: 0 === issues.length, issues },
+        integrity: {
+            clean: 0 === issues.length,
+            issues,
+            // Only when something was actually lost. An empty array beside `clean: true` would be a field
+            // that is always present and always says nothing, which is how a signal gets tuned out.
+            ...(0 === issues.length || undefined === inputs.losses || 0 === inputs.losses.length
+                ? {}
+                : { losses: [...new Set(inputs.losses)] }),
+        },
     };
 }
 /** Whether a verdict's honesty block clears the harness's bar. Reasons list every failed criterion. */

package/dist/honesty/verified.d.ts

@@ -14,6 +14,15 @@ import { type HonestyBlock } from './honesty.js';
 interface VerifiedInputs {
     /** Did the declared consequence hold? Undefined when the action declared none. */
     pass?: boolean;
+    /**
+     * The wait ended because the TAB went away, not because the app did anything.
+     *
+     * A structured flag rather than a match on `failureReason`, which is free prose everywhere else it
+     * is produced and describes what the APP did. A string test here would silently reclassify the
+     * next app-side reason that happened to mention a disconnect, which is the same
+     * confidently-wrong-by-accident this clause exists to remove.
+     */
+    observationLost?: boolean;
     honesty: HonestyBlock;
     /**
      * Set when the assertion could not be EVALUATED at all — an under-specified call, or nothing
@@ -47,7 +56,7 @@ interface VerifiedVerdict {
     verified: Verified;
     /**
      * WHICH clause below decided this, as a closed enum. `verified` has three values and this rule has
-     * ten clauses, so the verdict alone collapses opposite facts — "Reticle caught a real bug", "the
+     * eleven clauses, so the verdict alone collapses opposite facts — "Reticle caught a real bug", "the
      * agent wrote a bad predicate" and "Reticle could not see" all arrived as one string. Named here,
      * beside the sentence, so the vocabulary cannot drift from the branches that produce it.
      */

package/dist/honesty/verified.js

@@ -1,4 +1,4 @@
-import { Verified, VerifiedReason } from '@reticlehq/core';
+import { Verified, VerifiedReason, isAbsenceDerived } from '@reticlehq/core';
 import { HonestyGrade } from './honesty.js';
 export function decideVerified(inputs) {
     const { pass, honesty, contradictions = [], settled, outcomePending, outcomeUnread } = inputs;
@@ -12,6 +12,22 @@ export function decideVerified(inputs) {
             because: `the assertion could not be evaluated: ${inputs.inconclusive}`,
         };
     }
+    // ABOVE the failure clause, because a wait that ended when the tab vanished did not fail — it was
+    // never finished. `waitForPredicate` reports that as `pass: false`, and taking it at face value
+    // made Reticle blame the app, by file and line, for its own lost connection. Measured twice: a
+    // reload 300ms into a wait returned `verified:"no" / assertion_failed` against a healthy Counter.
+    //
+    // UNKNOWN, for the same reason `unclean_capture` is: the evidence is ABSENT, not negative.
+    if (true === inputs.observationLost) {
+        return {
+            verified: Verified.UNKNOWN,
+            verifiedReason: VerifiedReason.OBSERVATION_LOST,
+            because: 'the tab disconnected while this action was being observed, so its outcome was never ' +
+                'seen — this says nothing about the app. Call reticle_sessions for the current session ' +
+                '(a reloaded tab keeps its id; a closed one is gone) and repeat the action if it is safe ' +
+                'to repeat',
+        };
+    }
     // A failed assertion is the most actionable fact there is; it leads — including over
     // `alreadyTrue`, because a condition that held before AND fails now is a real regression.
     if (false === pass) {
@@ -25,14 +41,37 @@ export function decideVerified(inputs) {
     // 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(', ');
+    // ...but ONLY for contradictions we positively OBSERVED. A kind inferred from the absence of
+    // evidence — the request had not settled, the response had not been applied yet — is a statement
+    // about when we stopped looking, not about whether the action worked, and the window closes the
+    // moment the predicate first passes. Reproduced on the bench app: `auth:granted` fired with
+    // matching data, state changed, the token was stored, the capture was clean and the grade was
+    // `signal`, and the verdict was still NO because one POST was in flight. That inverts the grade
+    // hierarchy — a timing observation beat a consequence observation — and it is the shape of half of
+    // every `no` verdict in the field. See ABSENCE_DERIVED_CONTRADICTIONS for why a false negative
+    // costs more than it looks: it makes an agent redo work that succeeded, or stop believing the
+    // verdict channel, which is the product.
+    const observed = contradictions.filter((c) => !isAbsenceDerived(c.kind));
+    if (observed.length > 0) {
+        const kinds = observed.map((c) => c.kind).join(', ');
         return {
             verified: Verified.NO,
             verifiedReason: VerifiedReason.CONTRADICTED,
             because: `channels disagree about this action (${kinds}) even though the assertion passed`,
         };
     }
+    // Absence-derived only: report it, do not assert failure. UNKNOWN is the honest answer — Reticle
+    // drove the app and could not yet tell. The finding still rides out in `contradictions`, so an
+    // agent that wants to wait and re-check has everything it needs.
+    if (contradictions.length > 0) {
+        const kinds = contradictions.map((c) => c.kind).join(', ');
+        return {
+            verified: Verified.UNKNOWN,
+            verifiedReason: VerifiedReason.UNSETTLED,
+            because: `the assertion held, but this window closed before the app finished (${kinds}) — ` +
+                `re-check, or assert a consequence that settles`,
+        };
+    }
     // Below the contradiction clause, and for the same reason a contradiction outranks a dirty
     // capture: evidence AGAINST beats absence of evidence, whichever absence it is. Both can hold at
     // once — assert `{ text: 'Saved' }` that was already on screen while the write 500s — and ordering

package/dist/http-server.js

@@ -1,6 +1,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 { getSessionMetrics } from './telemetry/session-metrics.js';
 import { noteAgentPeer, PEER_VERSION_PARAM, PEER_CONTRACT_PARAM } from './version/peer-announce.js';
 import { log } from './log.js';
 import { reportMcpConnected } from './telemetry/mcp-connection.js';
@@ -85,6 +86,14 @@ export function createSharedServer(options = {}) {
                 transport.close().catch(() => undefined);
                 mcpServer.close().catch(() => undefined);
                 log('mcp_client_disconnected', { sessionId: sid });
+                // The one part of `endReason` a query cannot derive: "the client detached" and "the agent
+                // stopped asking" produce identical counters and are different findings.
+                try {
+                    getSessionMetrics().recordClientLeft();
+                }
+                catch {
+                    /* a counter must never affect a disconnect path */
+                }
                 if (0 === transports.size)
                     agentPresence?.(false); // last agent detached → it's the human's turn
             });
@@ -141,8 +150,18 @@ export function createSharedServer(options = {}) {
         transports.clear();
         await new Promise((resolve, reject) => {
             httpServer.close((err) => {
-                if (err !== undefined && err !== null)
+                // A server that never listened is already closed, and saying so is not an error worth
+                // propagating. It matters because this close() runs on the CLEANUP path of a failed
+                // `--drive`: when the app URL is unreachable, the daemon tears down before `listen()` has
+                // been called, Node rejects with ERR_SERVER_NOT_RUNNING, and that rejection REPLACES the
+                // real cause. The user's app is down and the message they read is "Server is not running",
+                // which blames Reticle for their dev server — traced live, where swallowing this turned the
+                // same failure back into "net::ERR_CONNECTION_REFUSED at http://localhost:4312/".
+                if (err !== undefined &&
+                    err !== null &&
+                    'ERR_SERVER_NOT_RUNNING' !== err.code) {
                     reject(err);
+                }
                 else
                     resolve();
             });

package/dist/index.d.ts

@@ -34,6 +34,7 @@ export type { Lease, Launcher, PooledBrowser } from './pool/browser-pool.js';
 export { playwrightLauncher, resolveMaxContexts } from './pool/playwright-launcher.js';
 export { appendReticleParams } from './tools/lease-tools.js';
 export { writePid, removePid, isRunning, logPath, readPid, isAlive } from './daemon/daemon.js';
+export { classifyDaemonLife, DaemonEnd, DAEMON_HEARTBEAT_EVENT, DAEMON_HEARTBEAT_MS, type DaemonLife, } from './daemon/heartbeat.js';
 export type { CrawlReport, CrawlAnomaly, CrawlOptions, CrawlSession } from './crawl/crawl.js';
 export { scrollToFind } from './input/scroll-find.js';
 export type { ScrollFindResult, ScrollFindQuery, ScrollFindSession } from './input/scroll-find.js';