@reticlehq/server 2.5.0 → 2.7.0

package/dist/daemon/state-dir.d.ts

@@ -0,0 +1,7 @@
+/**
+ * A sentence naming the problem, or `undefined` when the directory is usable.
+ *
+ * A directory that does not exist yet is NOT a problem: the daemon creates it, and the creation
+ * failing is caught by the same probe on the parent path.
+ */
+export declare function stateDirProblem(dir: string): string | undefined;

package/dist/daemon/state-dir.js

@@ -0,0 +1,59 @@
+/**
+ * Can Reticle write the directory it keeps everything in?
+ *
+ * `~/.reticle` holds the pid files, the daemon logs, the telemetry id and outbox, and every saved
+ * flow. A daemon that cannot write it does not start — and until now said nothing useful about why.
+ *
+ * Measured on 2.6.0 with `chmod 555 ~/.reticle`:
+ *
+ *   the daemon did not come up on :4415 — nothing is listening on :4415 — no daemon is running
+ *   see /…/.reticle/daemon-4415.log
+ *
+ * The first line restates the symptom. The second points at a log **inside the unwritable
+ * directory**, so the one diagnostic offered cannot exist. Someone hitting this — a locked-down home
+ * directory, a container with a read-only mount, a managed corporate profile — has nothing to go on.
+ *
+ * Deliberately a PROBE, not a permission-bit read: `stat` says what the mode claims, and an ACL, a
+ * read-only mount, SELinux or a full disk all produce a writable-looking mode and a failing write.
+ * The only honest test of "can I write here" is writing.
+ */
+import { mkdirSync, existsSync, writeFileSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+/** Probe filename. Distinctive so a leftover is obviously ours, and unlinked immediately either way. */
+const PROBE = '.reticle-write-probe';
+/**
+ * A sentence naming the problem, or `undefined` when the directory is usable.
+ *
+ * A directory that does not exist yet is NOT a problem: the daemon creates it, and the creation
+ * failing is caught by the same probe on the parent path.
+ */
+export function stateDirProblem(dir) {
+    if (!existsSync(dir)) {
+        // Not yet created is the ordinary first-run state. Only report if we cannot create it.
+        try {
+            mkdirSync(dir, { recursive: true });
+        }
+        catch {
+            return (`Reticle cannot create its state directory at ${dir}. Everything it keeps — the daemon ` +
+                'log, the pid file, saved flows — lives there, so the daemon cannot start. Check the ' +
+                'permissions on the parent directory, or point Reticle elsewhere with HOME.');
+        }
+        return undefined;
+    }
+    const probe = join(dir, PROBE);
+    try {
+        writeFileSync(probe, '', 'utf8');
+    }
+    catch {
+        return (`Reticle cannot write to its state directory at ${dir}. Everything it keeps — the daemon ` +
+            'log, the pid file, saved flows — lives there, so the daemon cannot start. Make it writable ' +
+            '(`chmod u+w`), or point Reticle elsewhere with HOME.');
+    }
+    try {
+        unlinkSync(probe);
+    }
+    catch {
+        /* wrote but could not clean up: the directory IS writable, which is the question asked */
+    }
+    return undefined;
+}

package/dist/daemon/unclean-predecessor.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The pid of a daemon that died without exiting, observed at the next start.
+ *
+ * `DaemonExitReason` covers every departure that goes through Node — signal, idle, and the
+ * load-bearing `unknown` for a stray exit or an uncaught throw. It cannot cover SIGKILL, an OOM
+ * kill, or a lost machine: no handler runs, so the log's last word about that daemon is whatever it
+ * happened to be doing. From the report (#123):
+ *
+ *   10:49:05  mcp_daemon_started        port:4400            <- pid 2884
+ *   10:51:29  mcp_daemon_started        port:4400  pid:4900  <- a SECOND daemon binds the SAME port
+ *
+ * pid 2884 died with no exit event at all, and the only evidence was that a second daemon could bind
+ * a port the first one held — something a reader has to notice and interpret.
+ *
+ * The next startup is the only place that death is observable, because it is the only moment
+ * anything looks at the pidfile the dead process left behind. A tidy shutdown unlinks its own, so
+ * finding one whose owner is gone IS the signal.
+ *
+ * Pure, and deliberately conservative: an owner that is still ALIVE is a port conflict, not a death,
+ * and accusing a live sibling of dying would be a new false claim in the log this exists to make
+ * honest.
+ */
+export declare function uncleanPredecessor(owner: number | null, alive: boolean, self: number): number | null;

package/dist/daemon/unclean-predecessor.js

@@ -0,0 +1,27 @@
+/**
+ * The pid of a daemon that died without exiting, observed at the next start.
+ *
+ * `DaemonExitReason` covers every departure that goes through Node — signal, idle, and the
+ * load-bearing `unknown` for a stray exit or an uncaught throw. It cannot cover SIGKILL, an OOM
+ * kill, or a lost machine: no handler runs, so the log's last word about that daemon is whatever it
+ * happened to be doing. From the report (#123):
+ *
+ *   10:49:05  mcp_daemon_started        port:4400            <- pid 2884
+ *   10:51:29  mcp_daemon_started        port:4400  pid:4900  <- a SECOND daemon binds the SAME port
+ *
+ * pid 2884 died with no exit event at all, and the only evidence was that a second daemon could bind
+ * a port the first one held — something a reader has to notice and interpret.
+ *
+ * The next startup is the only place that death is observable, because it is the only moment
+ * anything looks at the pidfile the dead process left behind. A tidy shutdown unlinks its own, so
+ * finding one whose owner is gone IS the signal.
+ *
+ * Pure, and deliberately conservative: an owner that is still ALIVE is a port conflict, not a death,
+ * and accusing a live sibling of dying would be a new false claim in the log this exists to make
+ * honest.
+ */
+export function uncleanPredecessor(owner, alive, self) {
+    if (null === owner || owner === self || alive)
+        return null;
+    return owner;
+}

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

@@ -58,11 +58,15 @@ export type Predicate = {
     kind: typeof PredicateKind.NOT;
     predicate: Predicate;
 };
+export declare const PredicateSchema: z.ZodType<Predicate>;
 /**
- * Strict on every branch. A key that is nobody's spelling is now a schema error naming it, instead of
- * a stripped field and a green — see predicate-strict.test.ts for the MCP session that found this.
+ * The fields a given predicate kind accepts, read off the schema itself.
+ *
+ * Derived rather than listed so the two can never disagree: a rejection message that names a stale
+ * field set is worse than one that names none, because the agent trusts it and retries into the same
+ * wall. Empty for a kind that is not in the union.
  */
-export declare const PredicateSchema: z.ZodType<Predicate>;
+export declare function predicateFieldsFor(kind: string): readonly string[];
 export interface EvalResult {
     pass: boolean;
     /**
@@ -83,6 +87,16 @@ export interface EvalResult {
     inconclusive?: string;
     evidence?: unknown;
     failureReason?: string;
+    /**
+     * The wait ended because the TAB went away, not because the app did anything observable.
+     *
+     * A sibling of `inconclusive` and for the same reason: `pass` is false because nothing was
+     * proven, but nobody could have made it true, so grading it as a defect in the user's app is a
+     * false claim. Without this the verdict rule saw only `pass: false` and answered
+     * `assertion_failed` — "the declared consequence did not hold" — naming the component the agent
+     * had just clicked. See VerifiedReason.OBSERVATION_LOST.
+     */
+    observationLost?: boolean;
     /**
      * The failure, structured — what was seen, what was required, and which oracle judged it.
      *

package/dist/events/predicate-eval.js

@@ -9,115 +9,188 @@ 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' },
+    // `text`/`value` on a `text` predicate: the kind is called "text", so `text:` is the first thing
+    // anyone writes for it, and `value` follows from the element query's own `value` field. Both were
+    // hard rejections, and a rejected predicate produces NO verdict at all — the drive ends with
+    // nothing rather than with a failure, which is the worst outcome of the three.
+    [PredicateKind.TEXT]: { text: 'contains', value: 'contains' },
+    // `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' },
 };
+/**
+ * Element-query fields an agent writes FLAT on an `element` predicate instead of nested under
+ * `query`. `reticle_query` takes exactly these at the top level, so an agent that has just located
+ * something writes the same words again when it asserts on it — and got `query: Required` plus an
+ * `unknown field` list for its trouble. Lifting them is unambiguous: they have no other meaning on
+ * this kind.
+ */
+const ELEMENT_QUERY_FIELDS = [
+    'by',
+    'value',
+    'role',
+    'name',
+    'text',
+    'label',
+    'placeholder',
+    'testid',
+    'alt',
+    'component',
+];
 /** Rename known aliases before parse; an explicit canonical key always wins. */
 function applyPredicateAliases(input) {
     if (typeof input !== 'object' || null === input || Array.isArray(input))
         return input;
     const obj = input;
-    const aliases = PREDICATE_ALIASES['string' === typeof obj['kind'] ? obj['kind'] : ''];
-    if (aliases === undefined)
-        return input;
+    const kind = 'string' === typeof obj['kind'] ? obj['kind'] : '';
+    const aliases = PREDICATE_ALIASES[kind];
+    let out = obj;
+    if (aliases !== undefined) {
+        out = { ...obj };
+        for (const [from, to] of Object.entries(aliases)) {
+            if (out[from] === undefined)
+                continue;
+            if (out[to] === undefined)
+                out[to] = out[from];
+            delete out[from];
+        }
+    }
+    return PredicateKind.ELEMENT === kind ? liftElementQuery(out) : out;
+}
+/**
+ * Fold flat query fields into `query`. An explicit `query` wins outright — a caller that supplied
+ * both told us which one it meant, and merging the two would invent a locator neither side wrote.
+ */
+function liftElementQuery(obj) {
+    const loose = ELEMENT_QUERY_FIELDS.filter((field) => obj[field] !== undefined);
+    if (0 === loose.length)
+        return obj;
     const out = { ...obj };
-    for (const [from, to] of Object.entries(aliases)) {
-        if (out[from] === undefined)
-            continue;
-        if (out[to] === undefined)
-            out[to] = out[from];
-        delete out[from];
+    const query = {};
+    for (const field of loose) {
+        query[field] = out[field];
+        delete out[field];
     }
+    if (out['query'] === undefined)
+        out['query'] = query;
     return out;
 }
 /**
  * Strict on every branch. A key that is nobody's spelling is now a schema error naming it, instead of
  * a stripped field and a green — see predicate-strict.test.ts for the MCP session that found this.
+ *
+ * Built on demand rather than at module scope: the `allOf`/`anyOf`/`not` branches reference
+ * `PredicateSchema` itself, which does not exist yet while this module is initialising. Calling it
+ * after init is what makes the union introspectable — see `predicateFieldsFor`.
+ */
+function predicateUnion() {
+    return z.discriminatedUnion('kind', [
+        z
+            .object({
+            kind: z.literal(PredicateKind.ELEMENT),
+            query: ElementQuerySchema,
+            state: z.nativeEnum(ElementState).optional(),
+            absent: z.boolean().optional(),
+        })
+            .strict(),
+        z
+            .object({
+            kind: z.literal(PredicateKind.TEXT),
+            contains: z.string(),
+            visible: z.boolean().optional(),
+            absent: z.boolean().optional(),
+        })
+            .strict(),
+        z
+            .object({
+            kind: z.literal(PredicateKind.NET),
+            method: z.string().optional(),
+            urlContains: z.string().optional(),
+            status: z.number().optional(),
+            ok: z.boolean().optional(),
+            since: z.number().optional(),
+            count: z.number().int().nonnegative().optional(),
+        })
+            .strict(),
+        z
+            .object({
+            kind: z.literal(PredicateKind.ROUTE),
+            pathname: z.string().optional(),
+            contains: z.string().optional(),
+            since: z.number().optional(),
+        })
+            .strict(),
+        z
+            .object({
+            kind: z.literal(PredicateKind.CONSOLE),
+            level: z.string().optional(),
+            absent: z.boolean().optional(),
+            since: z.number().optional(),
+        })
+            .strict(),
+        z
+            .object({
+            kind: z.literal(PredicateKind.ANIMATION),
+            name: z.string().optional(),
+            target: z.string().optional(),
+            completed: z.boolean().optional(),
+            since: z.number().optional(),
+        })
+            .strict(),
+        z
+            .object({
+            kind: z.literal(PredicateKind.SIGNAL),
+            name: z.string().optional(),
+            dataMatches: z.record(z.unknown()).optional(),
+            since: z.number().optional(),
+        })
+            .strict(),
+        z
+            .object({
+            kind: z.literal(PredicateKind.STATE),
+            store: z.string().optional(),
+            path: z.string(),
+            equals: z.unknown().optional(),
+        })
+            .strict(),
+        z
+            .object({
+            kind: z.literal(PredicateKind.SETTLED),
+            quietMs: z.number().positive().optional(),
+        })
+            .strict(),
+        z
+            .object({ kind: z.literal(PredicateKind.ALL_OF), predicates: z.array(PredicateSchema) })
+            .strict(),
+        z
+            .object({ kind: z.literal(PredicateKind.ANY_OF), predicates: z.array(PredicateSchema) })
+            .strict(),
+        z.object({ kind: z.literal(PredicateKind.NOT), predicate: PredicateSchema }).strict(),
+    ]);
+}
+export const PredicateSchema = z.lazy(() => z.preprocess(applyPredicateAliases, predicateUnion()));
+/**
+ * The fields a given predicate kind accepts, read off the schema itself.
+ *
+ * Derived rather than listed so the two can never disagree: a rejection message that names a stale
+ * field set is worse than one that names none, because the agent trusts it and retries into the same
+ * wall. Empty for a kind that is not in the union.
  */
-export const PredicateSchema = z.lazy(() => z.preprocess(applyPredicateAliases, z.discriminatedUnion('kind', [
-    z
-        .object({
-        kind: z.literal(PredicateKind.ELEMENT),
-        query: ElementQuerySchema,
-        state: z.nativeEnum(ElementState).optional(),
-        absent: z.boolean().optional(),
-    })
-        .strict(),
-    z
-        .object({
-        kind: z.literal(PredicateKind.TEXT),
-        contains: z.string(),
-        visible: z.boolean().optional(),
-        absent: z.boolean().optional(),
-    })
-        .strict(),
-    z
-        .object({
-        kind: z.literal(PredicateKind.NET),
-        method: z.string().optional(),
-        urlContains: z.string().optional(),
-        status: z.number().optional(),
-        ok: z.boolean().optional(),
-        since: z.number().optional(),
-        count: z.number().int().nonnegative().optional(),
-    })
-        .strict(),
-    z
-        .object({
-        kind: z.literal(PredicateKind.ROUTE),
-        pathname: z.string().optional(),
-        contains: z.string().optional(),
-        since: z.number().optional(),
-    })
-        .strict(),
-    z
-        .object({
-        kind: z.literal(PredicateKind.CONSOLE),
-        level: z.string().optional(),
-        absent: z.boolean().optional(),
-        since: z.number().optional(),
-    })
-        .strict(),
-    z
-        .object({
-        kind: z.literal(PredicateKind.ANIMATION),
-        name: z.string().optional(),
-        target: z.string().optional(),
-        completed: z.boolean().optional(),
-        since: z.number().optional(),
-    })
-        .strict(),
-    z
-        .object({
-        kind: z.literal(PredicateKind.SIGNAL),
-        name: z.string().optional(),
-        dataMatches: z.record(z.unknown()).optional(),
-        since: z.number().optional(),
-    })
-        .strict(),
-    z
-        .object({
-        kind: z.literal(PredicateKind.STATE),
-        store: z.string().optional(),
-        path: z.string(),
-        equals: z.unknown().optional(),
-    })
-        .strict(),
-    z
-        .object({
-        kind: z.literal(PredicateKind.SETTLED),
-        quietMs: z.number().positive().optional(),
-    })
-        .strict(),
-    z
-        .object({ kind: z.literal(PredicateKind.ALL_OF), predicates: z.array(PredicateSchema) })
-        .strict(),
-    z
-        .object({ kind: z.literal(PredicateKind.ANY_OF), predicates: z.array(PredicateSchema) })
-        .strict(),
-    z.object({ kind: z.literal(PredicateKind.NOT), predicate: PredicateSchema }).strict(),
-])));
+export function predicateFieldsFor(kind) {
+    for (const option of predicateUnion().options) {
+        const literal = option.shape['kind'];
+        if (literal instanceof z.ZodLiteral && literal.value === kind) {
+            return Object.keys(option.shape).filter((field) => 'kind' !== field);
+        }
+    }
+    return [];
+}
 function str(value) {
     return 'string' === typeof value ? value : undefined;
 }
@@ -208,6 +281,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 +337,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.
+ *
+ * In the field a meaningful share of all tool errors 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,68 @@
+/**
+ * One readable sentence when a predicate does not parse — never the zod array.
+ *
+ * In the field a meaningful share of all tool errors 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 { PredicateKind } from '@reticlehq/core';
+import { PredicateSchema, predicateFieldsFor } 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. ${accepted(kind)} ` +
+        `A valid call looks like: ${EXAMPLE}`);
+}
+/**
+ * What WOULD have worked, in the same breath as what did not.
+ *
+ * Telling an agent only which field is wrong leaves it guessing again, and each guess costs another
+ * round trip on the one call path that produces verdicts. Naming the accepted fields — or, when the
+ * kind itself is the mistake, the accepted kinds — makes the retry informed instead.
+ */
+function accepted(kind) {
+    const fields = predicateFieldsFor(kind);
+    if (0 < fields.length)
+        return `${kind} accepts: ${fields.join(', ')}.`;
+    return `"${kind}" is not a predicate kind — use one of: ${Object.values(PredicateKind).join(', ')}.`;
+}

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.d.ts

@@ -24,6 +24,14 @@ export declare class RingBuffer {
     since(cursor: number): ReticleEvent[];
     /** Events within the last `windowMs`, relative to `now`. */
     window(windowMs: number, now: number): ReticleEvent[];
+    /**
+     * 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: number): boolean;
     /** Snapshot of buffer health for the agent — live events held and cumulative drops since connect. */
     bufferHealth(): {
         total: number;