@reticlehq/server 2.5.0 → 2.6.0

package/dist/events/predicate-eval.js

@@ -9,7 +9,13 @@ import { describeObserved } from './observed-in-window.js';
  * the only key supplied left a predicate that asserts nothing and passes on anything.
  */
 const PREDICATE_ALIASES = {
-    [PredicateKind.ROUTE]: { path: 'pathname' },
+    // `urlContains`/`url` reported from the field: an agent that had just written
+    // `net { urlContains }` applied the same word to `route`, which spells it `contains`, and got
+    // `unrecognized_keys` with no list of what would have worked. The parallel it assumed is a fair
+    // one — route's `contains` matches the WHOLE route (path + query + fragment), so "the URL
+    // contains this" is precisely what it does — and asserting a redirect after login is the single
+    // most common thing an agent reaches for here.
+    [PredicateKind.ROUTE]: { path: 'pathname', urlContains: 'contains', url: 'contains' },
     [PredicateKind.NET]: { url: 'urlContains' },
     [PredicateKind.SIGNAL]: { data: 'dataMatches' },
 };
@@ -208,6 +214,22 @@ function callSucceeded(data) {
     const status = num(data['status']);
     return status === undefined || status < 400;
 }
+/**
+ * One call, as the failure report should name it: `POST /api/generate-script → 500`.
+ *
+ * The status used to be dropped here, which made the most common net failure unreadable. Asserting
+ * `{status: 200}` against a call that returned 500 reported only `POST /api/generate-script` — the
+ * very field the predicate filtered on was missing from the account of what was seen, so the agent
+ * is told the call happened and left to guess why it did not match.
+ *
+ * The arrow is OMITTED when there is no status. An in-flight or aborted request genuinely has none,
+ * and `→ undefined` would be a fabricated fact about the wire.
+ */
+function describeCall(e) {
+    const head = `${str(e.data['method']) ?? 'GET'} ${str(e.data['url']) ?? ''}`;
+    const status = num(e.data['status']);
+    return status === undefined ? head : `${head} → ${String(status)}`;
+}
 export function evalNet(events, p) {
     const since = p.since ?? 0;
     const matches = events.filter((e) => {
@@ -248,9 +270,7 @@ export function evalNet(events, p) {
             failureReason: `no network call matched ${JSON.stringify(p)}`,
             // Same reasoning as the signal miss: "no matching call" cannot be told apart from "the app
             // made no calls at all", and those need different fixes.
-            observed: describeObserved('calls', events
-                .filter((e) => e.type === EventType.NET_REQUEST)
-                .map((e) => `${str(e.data['method']) ?? 'GET'} ${str(e.data['url']) ?? ''}`)),
+            observed: describeObserved('calls', events.filter((e) => e.type === EventType.NET_REQUEST).map(describeCall)),
             expected: `at least one call matching ${JSON.stringify(p)}`,
             assertion: 'net.present',
         };

package/dist/events/predicate-parse.d.ts

@@ -0,0 +1,23 @@
+/**
+ * One readable sentence when a predicate does not parse — never the zod array.
+ *
+ * Measured 2026-08-10: **9 of 58 tool errors that day were a serialized zod issue array**, all on
+ * `reticle_act_and_wait`, `reticle_wait_for` and `reticle_assert` — the three tools that produced
+ * every action-derived finding in the dataset. The least readable error we emit was landing on the
+ * highest-value path, and an agent had to `JSON.parse` an error string to learn which field it got
+ * wrong.
+ *
+ * `PredicateSchema.parse()` throws a `ZodError` whose `.message` IS that array, and three handlers
+ * call it directly. This wraps it once, so every caller gets the same shape rather than each
+ * growing its own catch — the pattern #108 asks for: name the parameter, say whether anything ran,
+ * show a valid call.
+ */
+import { z } from 'zod';
+import { PredicateSchema } from './predicate-eval.js';
+/**
+ * Parse a predicate, or throw an Error whose message is a sentence.
+ *
+ * Deliberately still THROWS: every call site already handles a throw, and turning this into a
+ * result type would mean touching three handlers to gain nothing the message does not already say.
+ */
+export declare function parsePredicate(input: unknown): z.infer<typeof PredicateSchema>;

package/dist/events/predicate-parse.js

@@ -0,0 +1,54 @@
+/**
+ * One readable sentence when a predicate does not parse — never the zod array.
+ *
+ * Measured 2026-08-10: **9 of 58 tool errors that day were a serialized zod issue array**, all on
+ * `reticle_act_and_wait`, `reticle_wait_for` and `reticle_assert` — the three tools that produced
+ * every action-derived finding in the dataset. The least readable error we emit was landing on the
+ * highest-value path, and an agent had to `JSON.parse` an error string to learn which field it got
+ * wrong.
+ *
+ * `PredicateSchema.parse()` throws a `ZodError` whose `.message` IS that array, and three handlers
+ * call it directly. This wraps it once, so every caller gets the same shape rather than each
+ * growing its own catch — the pattern #108 asks for: name the parameter, say whether anything ran,
+ * show a valid call.
+ */
+import { z } from 'zod';
+import { PredicateSchema } from './predicate-eval.js';
+/** A valid call, short enough to sit inside an error without becoming the error. */
+const EXAMPLE = '{ kind: "signal", name: "todos:loaded" }';
+/** `path: ["net","urlContains"]` → `net.urlContains`; an empty path means the object itself. */
+function pathOf(issue) {
+    return 0 === issue.path.length ? 'the predicate' : issue.path.map(String).join('.');
+}
+/**
+ * One issue, as a clause a human or an agent can act on.
+ *
+ * `unrecognized_keys` is the common case by far and the one worth spelling out — it is what a
+ * plausible-but-wrong field name produces, and the key itself is the whole answer.
+ */
+function describeIssue(issue) {
+    if (z.ZodIssueCode.unrecognized_keys === issue.code) {
+        return `unknown field ${issue.keys.join(', ')}`;
+    }
+    return `${pathOf(issue)}: ${issue.message}`;
+}
+/**
+ * Parse a predicate, or throw an Error whose message is a sentence.
+ *
+ * Deliberately still THROWS: every call site already handles a throw, and turning this into a
+ * result type would mean touching three handlers to gain nothing the message does not already say.
+ */
+export function parsePredicate(input) {
+    const parsed = PredicateSchema.safeParse(input);
+    if (parsed.success)
+        return parsed.data;
+    const kind = 'object' === typeof input && null !== input && 'kind' in input
+        ? String(input['kind'])
+        : 'unknown';
+    // Bounded on purpose: a union rejection can produce one issue per member, and pasting all of them
+    // back is how the zod array became unreadable in the first place.
+    const issues = parsed.error.issues.slice(0, 3).map(describeIssue).join('; ');
+    throw new Error(`that predicate did not parse (kind "${kind}"): ${issues}. Nothing ran — the predicate was ` +
+        `not evaluated, so no verdict was produced. Call reticle_tools for the fields this kind ` +
+        `accepts. A valid call looks like: ${EXAMPLE}`);
+}

package/dist/events/predicate.d.ts

@@ -17,6 +17,11 @@ export interface PredicateSession {
      * Optional: a session without ambient learning simply omits it and settle behaves as before.
      */
     ambientCounts?(): AmbientCounts;
+    /**
+     * Subscribe to session disconnect. Returns an unsubscribe function. Optional: a session without
+     * this hook (e.g. tests that never disconnect) simply leaves in-flight predicates until timeout.
+     */
+    onDisconnect?(listener: () => void): () => void;
 }
 export declare function evaluatePredicate(session: PredicateSession, predicate: Predicate, since?: number, diagnose?: boolean): Promise<EvalResult>;
 /**

package/dist/events/predicate.js

@@ -305,6 +305,7 @@ export function waitForPredicate(session, predicate, timeoutMs, since = 0) {
                 return;
             done = true;
             unsub();
+            unsubDisconnect?.();
             clearInterval(interval);
             clearTimeout(timer);
             if (cooldownTimer !== undefined)
@@ -398,6 +399,13 @@ export function waitForPredicate(session, predicate, timeoutMs, since = 0) {
          * rejection reached it as an unhandledRejection. Either way the wait never resolved and the tool
          * handler never returned — the agent sees a call that simply never comes back.
          *
+         * This half covers the SYNCHRONOUS throw only. The rejection half is handled inside `check`, by
+         * the `.catch` on its own promise chain — `check` returns void and voids the promise it starts,
+         * so there is nothing to hand back here to await. Said explicitly because the obvious-looking
+         * `if (result instanceof Promise) result.catch(…)` that used to sit here was dead code that read
+         * like the rejection guard, and removing `check`'s own `.catch` as redundant would have restored
+         * the exact hang this exists to prevent.
+         *
          * That is the exact shape reported from a Plane (Next 14 + MobX) session, which tears the page
          * session down and rebuilds it on EVERY navigation, so a `{kind:"route"}` predicate always races
          * a teardown of the very session it is watching: `browser.command ok:true` for the click, and
@@ -407,9 +415,7 @@ export function waitForPredicate(session, predicate, timeoutMs, since = 0) {
          */
         const guardedCheck = () => {
             try {
-                const pending = check();
-                if (pending instanceof Promise)
-                    pending.catch(failWait);
+                check();
             }
             catch (error) {
                 failWait(error);
@@ -424,6 +430,14 @@ export function waitForPredicate(session, predicate, timeoutMs, since = 0) {
         const unsub = session.onEvent(() => {
             boundCheck();
         });
+        const unsubDisconnect = session.onDisconnect?.(() => {
+            // `observationLost` is what stops this being graded as an app defect. `pass: false` is still
+            // correct — the consequence was not seen to hold — but on its own it reached the verdict rule
+            // as ASSERTION_FAILED, so a reload mid-wait reported "the declared consequence did not hold"
+            // against a healthy component, by file and line. The flag is structured rather than inferred
+            // from this string, because every other `failureReason` here is prose about the APP.
+            finish({ pass: false, failureReason: 'session disconnected', observationLost: true });
+        });
         const interval = setInterval(boundCheck, POLL_INTERVAL_MS);
         const timer = setTimeout(() => {
             void evaluatePredicate(session, predicate, since)

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;
 /**

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/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

@@ -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) {

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

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';