@reticlehq/server 2.6.0 → 2.7.0

package/dist/cli.js

@@ -132,6 +132,10 @@ async function serveWithHonestExit(parsed) {
 /** How long `serve` waits for the child to bind. Generous: a cold daemon start is seconds. */
 const SERVE_BIND_TIMEOUT_MS = 15_000;
 const PRESENCE_POLL_MS = 150;
+/** How long a daemon gets to shut down on its own before `stop` stops asking politely. */
+const GRACEFUL_STOP_MS = 5000;
+/** How long after SIGKILL before we accept the process is not ours to kill and say so. */
+const FORCED_STOP_MS = 2000;
 async function waitForPresence(port, want, timeoutMs) {
     const deadline = Date.now() + timeoutMs;
     for (;;) {
@@ -153,18 +157,35 @@ function handleStop(port, quiet) {
     }
     process.kill(pid, 'SIGTERM');
     const started = Date.now();
+    let escalated = false;
     const poll = setInterval(() => {
         if (!isAlive(pid)) {
             clearInterval(poll);
             removePid(port);
             if (!quiet)
-                log('reticle_daemon_stopped', { port, pid });
+                log('reticle_daemon_stopped', { port, pid, ...(escalated ? { escalated } : {}) });
             return;
         }
-        if (Date.now() - started > 5000) {
+        const waited = Date.now() - started;
+        // A daemon that ignores SIGTERM is WEDGED — which is the one situation `stop` exists for. Giving
+        // up here left the port held, the pid file stale, and a human running `kill -9` by hand at the
+        // first two minutes of setup. Escalate instead: graceful first, then unconditional.
+        if (!escalated && waited > GRACEFUL_STOP_MS) {
+            escalated = true;
+            try {
+                process.kill(pid, 'SIGKILL');
+            }
+            catch {
+                // Already gone between the liveness check and here — the next tick reports it stopped.
+            }
+            return;
+        }
+        if (waited > GRACEFUL_STOP_MS + FORCED_STOP_MS) {
             clearInterval(poll);
+            // Surviving SIGKILL means the pid is not ours to kill (permissions) or is an unkillable
+            // zombie. Neither is retryable, and both need the pid named so a human can act on it.
             if (!quiet)
-                log('reticle_daemon_stop_timeout', { port, pid });
+                log('reticle_daemon_stop_timeout', { port, pid, escalated });
             process.exit(1);
         }
     }, 100);
@@ -360,11 +381,21 @@ function handleOpen(requestedPort, url) {
             ...(connected
                 ? {}
                 : {
-                    note: 'the browser was launched but no Reticle session appeared. The app may still be ' +
-                        'loading, or it is not wired to this bridge — run `reticle doctor`, and check the ' +
-                        'app connects on port ' +
-                        String(port) +
-                        '.',
+                    // Two claims used to live here that this command cannot support. It said the browser
+                    // "was launched" — it asked the OS to open a URL and cannot see whether a window
+                    // appeared — and it offered "the app may still be loading" as a cause with equal
+                    // weight to the real one. It then pointed at `reticle doctor`, whose Chromium check is
+                    // about a browser THIS command never uses, so a missing Chromium reads as the
+                    // explanation for a session that is missing for an unrelated reason. Both misdirects
+                    // were reported from the field, each costing several calls of app-side wiring hunt.
+                    note: `the URL was handed to the system default browser (this command does not use ` +
+                        `Reticle's own Chromium, so a chromium warning from \`reticle doctor\` is unrelated ` +
+                        `to this). No Reticle session appeared. By far the likeliest cause is that the app ` +
+                        `carries no Reticle SDK, or dials a port other than ${String(port)} — run ` +
+                        `\`reticle init\` in the app's directory and restart its dev server. If the app IS ` +
+                        `wired, give the page a moment and check the browser console: the SDK announces its ` +
+                        `own connect failures there, including the one it refuses to make from a ` +
+                        `non-localhost host without allowNonLocalhost.`,
                 }),
         });
     })
@@ -420,7 +451,7 @@ function handleDaemonInner(parsed) {
                 // The reason rides out on the session summary, which is the only event that fires at this
                 // exact moment. The proxy emits the matching `mcp_connection_lost` and cannot know it —
                 // it sees a socket end and nothing more, which is how a scheduled idle exit came to make up
-                // 299 of 321 "outages". See SessionSummary.exit.
+                // the large majority of "outages". See SessionSummary.exit.
                 .shutdown(reason)
                 .then(() => server.close())
                 .then(() => {

package/dist/daemon/daemon-resilience.js

@@ -42,8 +42,8 @@ const DISCONNECT_CODES = new Set([
 /**
  * Nobody went away — nobody was ever there. A refused connect is the daemon not being up YET.
  *
- * This is the difference that made `runtime_crashed` useless. Measured 2026-08-10/11: **84 of 84
- * crash events were one fingerprint, `connect ECONNREFUSED`, and every affected user was in the
+ * This is the difference that made `runtime_crashed` useless. In the field **every crash event
+ * carried one fingerprint, `connect ECONNREFUSED`, and every affected user was in the
  * never-verified set.** The proxy is BUILT to tolerate this — it answers the handshake from cache
  * and wakes a daemon on the next request — so reporting it as a crash meant the one metric that is
  * supposed to say "Reticle broke" said nothing but "the daemon had not booted yet", and a real crash

package/dist/daemon/loopback-alias.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Serve the IPv4-bound daemon on IPv6 loopback too, so `localhost` reaches it on every platform.
+ *
+ * The daemon binds `127.0.0.1` — deliberately, because Reticle must never be reachable off-host. But
+ * `localhost` is a NAME, and on Windows Chrome resolves it to `::1` before `127.0.0.1`. The SDK's
+ * default bridge URL says `localhost`. So on the platform that is most of our installs, and the
+ * browser that is most of that, the documented default cannot connect — and the error text names the
+ * daemon, containers and WSL, none of which is the cause.
+ *
+ * This is a byte forwarder rather than a second `http.Server` on purpose. The daemon speaks HTTP,
+ * WebSocket upgrades and SSE on one port; copying request/upgrade wiring onto a second server means a
+ * second place to keep in sync, and the first handler anybody forgets to mirror becomes a bug that
+ * only Windows sees. A TCP pipe carries all three and cannot drift from what it forwards.
+ *
+ * Best-effort by contract: a machine with IPv6 disabled, or something already holding `[::1]:port`,
+ * leaves the daemon exactly as it was before. Never fatal — this widens reachability, it is not a
+ * precondition for serving.
+ */
+/** IPv6 loopback. The other half of what `localhost` can mean. */
+export declare const IPV6_LOOPBACK = "::1";
+export interface LoopbackAlias {
+    /** False when the alias could not be bound — the daemon still serves IPv4 as before. */
+    opened: boolean;
+    close: () => Promise<void>;
+}
+/**
+ * Accept on `[::1]:port` and pipe each connection to `127.0.0.1:port`.
+ *
+ * Both ends are loopback, so a forwarded peer is still a loopback peer and the bridge's loopback
+ * trust holds — the alias does not widen who may connect, only which address they may name.
+ */
+export declare function openLoopbackAlias(port: number): Promise<LoopbackAlias>;

package/dist/daemon/loopback-alias.js

@@ -0,0 +1,80 @@
+/**
+ * Serve the IPv4-bound daemon on IPv6 loopback too, so `localhost` reaches it on every platform.
+ *
+ * The daemon binds `127.0.0.1` — deliberately, because Reticle must never be reachable off-host. But
+ * `localhost` is a NAME, and on Windows Chrome resolves it to `::1` before `127.0.0.1`. The SDK's
+ * default bridge URL says `localhost`. So on the platform that is most of our installs, and the
+ * browser that is most of that, the documented default cannot connect — and the error text names the
+ * daemon, containers and WSL, none of which is the cause.
+ *
+ * This is a byte forwarder rather than a second `http.Server` on purpose. The daemon speaks HTTP,
+ * WebSocket upgrades and SSE on one port; copying request/upgrade wiring onto a second server means a
+ * second place to keep in sync, and the first handler anybody forgets to mirror becomes a bug that
+ * only Windows sees. A TCP pipe carries all three and cannot drift from what it forwards.
+ *
+ * Best-effort by contract: a machine with IPv6 disabled, or something already holding `[::1]:port`,
+ * leaves the daemon exactly as it was before. Never fatal — this widens reachability, it is not a
+ * precondition for serving.
+ */
+import net from 'node:net';
+import { LOOPBACK_HOST } from '@reticlehq/core';
+/** IPv6 loopback. The other half of what `localhost` can mean. */
+export const IPV6_LOOPBACK = '::1';
+/**
+ * Accept on `[::1]:port` and pipe each connection to `127.0.0.1:port`.
+ *
+ * Both ends are loopback, so a forwarded peer is still a loopback peer and the bridge's loopback
+ * trust holds — the alias does not widen who may connect, only which address they may name.
+ */
+export function openLoopbackAlias(port) {
+    /** Every socket this alias has open, so shutdown can end them instead of waiting them out. */
+    const live = new Set();
+    const server = net.createServer((inbound) => {
+        const outbound = net.connect(port, LOOPBACK_HOST);
+        live.add(inbound).add(outbound);
+        const drop = (socket) => {
+            live.delete(socket);
+        };
+        inbound.on('close', () => drop(inbound));
+        outbound.on('close', () => drop(outbound));
+        // A dead peer on either side must tear down the pair, not surface as an unhandled 'error'
+        // event — which in Node terminates the daemon this alias exists to make reachable.
+        inbound.on('error', () => outbound.destroy());
+        outbound.on('error', () => inbound.destroy());
+        inbound.pipe(outbound);
+        outbound.pipe(inbound);
+    });
+    return new Promise((resolve) => {
+        /**
+         * Stop listening and END EVERYTHING, rather than draining.
+         *
+         * `server.close()` fires its callback only once every existing connection has gone, so a single
+         * held-open socket — a keep-alive, an SSE stream, exactly what this daemon serves — means the
+         * callback never fires. The daemon's shutdown chain awaits this, so an un-drained alias silently
+         * became a daemon that ignores SIGTERM: `reticle stop` timed out, the process stayed alive, and
+         * the port stayed held. Caught by the heartbeat spec, which is the one gate that watches a
+         * daemon actually die.
+         *
+         * A best-effort side listener must never be able to hold up the shutdown of the thing it exists
+         * to make reachable. We are exiting; ending these sockets is the correct outcome, not a
+         * compromise.
+         */
+        const close = () => new Promise((done) => {
+            server.close(() => done());
+            for (const socket of live)
+                socket.destroy();
+            live.clear();
+        });
+        server.once('error', () => {
+            // Nothing was bound, so there is nothing to close — but the caller still gets a close it can
+            // call unconditionally, rather than a shape it has to branch on.
+            resolve({ opened: false, close: () => Promise.resolve() });
+        });
+        server.listen(port, IPV6_LOOPBACK, () => {
+            // Never the reason the process stays up: if the daemon is otherwise done, this must not be
+            // what keeps the event loop alive.
+            server.unref();
+            resolve({ opened: true, close });
+        });
+    });
+}

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

package/dist/events/predicate-eval.js

@@ -9,6 +9,11 @@ import { describeObserved } from './observed-in-window.js';
  * the only key supplied left a predicate that asserts nothing and passes on anything.
  */
 const PREDICATE_ALIASES = {
+    // `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
@@ -19,111 +24,173 @@ const PREDICATE_ALIASES = {
     [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;
 }

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

@@ -1,7 +1,7 @@
 /**
  * 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
+ * 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

package/dist/events/predicate-parse.js

@@ -1,7 +1,7 @@
 /**
  * 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
+ * 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
@@ -13,7 +13,8 @@
  * show a valid call.
  */
 import { z } from 'zod';
-import { PredicateSchema } from './predicate-eval.js';
+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. */
@@ -49,6 +50,19 @@ export function parsePredicate(input) {
     // 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}`);
+        `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/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;

package/dist/events/ring-buffer.js

@@ -23,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;
@@ -81,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;
@@ -91,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;
         }
@@ -102,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);