@reticlehq/server 2.10.0 → 2.12.0

package/dist/daemon/free-port.js

@@ -0,0 +1,55 @@
+/**
+ * A port this machine will actually let us bind.
+ *
+ * Once daemons are per-project, "which port" stops being a constant and becomes a question. The
+ * answer must not be "the next number up": probing 4401, 4402, 4403 races every other agent doing
+ * the same arithmetic at the same moment, and the loser finds out at bind time, which is after it has
+ * already told the caller which port to use.
+ *
+ * So the OS assigns it. Binding port 0 asks the kernel for a free one and hands back the number it
+ * chose, and nothing else can be holding it at that instant. There is still a window between closing
+ * the probe socket and the daemon binding for real — unavoidable without passing the listener itself
+ * to the child — but it is microseconds wide and loses to a retry, where a guessed number loses every
+ * time on a busy machine.
+ *
+ * The preferred port is tried first so the ordinary single-project install keeps landing on the
+ * documented default, and every doc, log line and troubleshooting page that says 4400 stays true.
+ */
+import { createServer } from 'node:net';
+import { LOOPBACK_HOST } from '@reticlehq/core';
+/** Can we bind `port` on the loopback interface right now? */
+export function portIsFree(port, host = LOOPBACK_HOST) {
+    return new Promise((resolve) => {
+        const probe = createServer();
+        probe.once('error', () => resolve(false));
+        probe.listen(port, host, () => {
+            probe.close(() => resolve(true));
+        });
+    });
+}
+/** Ask the kernel for a free port. Rejects only if the machine cannot bind loopback at all. */
+export function osAssignedPort(host = LOOPBACK_HOST) {
+    return new Promise((resolve, reject) => {
+        const probe = createServer();
+        probe.once('error', reject);
+        probe.listen(0, host, () => {
+            const address = probe.address();
+            if (null === address || 'string' === typeof address) {
+                probe.close(() => reject(new Error('could not read an OS-assigned port')));
+                return;
+            }
+            const { port } = address;
+            probe.close(() => resolve(port));
+        });
+    });
+}
+/**
+ * `preferred` when it is free, otherwise whatever the OS gives us.
+ *
+ * Injectable so the decision is unit-testable without binding anything: the interesting case is the
+ * one where the preferred port is taken, and a test must be able to say so without racing a real
+ * socket.
+ */
+export async function pickDaemonPortToBind(preferred, isFree = portIsFree, assign = osAssignedPort) {
+    return (await isFree(preferred)) ? preferred : assign();
+}

package/dist/daemon/heartbeat.d.ts

@@ -19,10 +19,6 @@
  */
 /** The event name a beat carries. One `grep` separates liveness from everything else in the file. */
 export declare const DAEMON_HEARTBEAT_EVENT = "reticle_daemon_alive";
-/** Written by installExitTrace when the process exits through Node. */
-export declare const DAEMON_EXIT_EVENT = "reticle_daemon_exiting";
-/** Written by installExitTrace when a signal arrives, which is a CAUSE the exit line does not carry. */
-export declare const DAEMON_SIGNAL_EVENT = "reticle_daemon_signalled";
 /**
  * How often a live daemon says so.
  *

package/dist/daemon/heartbeat.js

@@ -20,9 +20,9 @@
 /** The event name a beat carries. One `grep` separates liveness from everything else in the file. */
 export const DAEMON_HEARTBEAT_EVENT = 'reticle_daemon_alive';
 /** Written by installExitTrace when the process exits through Node. */
-export const DAEMON_EXIT_EVENT = 'reticle_daemon_exiting';
+const DAEMON_EXIT_EVENT = 'reticle_daemon_exiting';
 /** Written by installExitTrace when a signal arrives, which is a CAUSE the exit line does not carry. */
-export const DAEMON_SIGNAL_EVENT = 'reticle_daemon_signalled';
+const DAEMON_SIGNAL_EVENT = 'reticle_daemon_signalled';
 /**
  * How often a live daemon says so.
  *

package/dist/dev/stale-issue-guard.d.ts

@@ -0,0 +1,41 @@
+/**
+ * An issue we have already fixed must not still read as available work.
+ *
+ * Three contributor PRs died on arrival in one week for this. #373 was filed at 09:52 and fixed by
+ * us at 12:33 the same day, then left open for three more days — somebody started on it on day two.
+ * #398 shipped and stayed open; a second contributor rebuilt it from scratch. `GITHUB.md` already
+ * documents the same failure costing three contributors before either of those, which makes this the
+ * third recurrence of a defect we have written down and asked ourselves to remember.
+ *
+ * Remembering is not a mechanism, and this is the smallest one that works: a commit saying it closes
+ * an issue is a claim that the issue is done. If that issue is still open and unlabelled afterwards,
+ * the tracker is lying to whoever reads it next — and the person it lies to is by definition someone
+ * looking for something to work on.
+ *
+ * ## Why `fixed-pending-release` is an accepted answer
+ *
+ * Work fixed on an unreleased branch is legitimately still open; the issue closes when the version
+ * ships. The label is what tells a contributor not to start, so the label — not the closure — is
+ * what this guard is actually asking for. That is also why the fix is cheap: nobody has to change
+ * when they close things, only to say so.
+ *
+ * Pure. The git log and the GitHub lookup belong to the caller, which is what makes every branch
+ * below testable without a network or a repo.
+ */
+export interface IssueState {
+    number: number;
+    state: 'open' | 'closed';
+    labels: readonly string[];
+}
+export declare function closedRefsIn(commitMessage: string): number[];
+/**
+ * Of the issues these commits claimed to close, the ones still reading as available work.
+ *
+ * An issue that could not be looked up is deliberately silent rather than failing. A rate limit, a
+ * transferred issue or a deleted one would otherwise turn this red for a reason unrelated to what it
+ * guards, and a guard that goes red for unrelated reasons gets disabled — which costs more than the
+ * defect it was catching.
+ */
+export declare function staleIssues(claimed: readonly number[], issues: readonly IssueState[]): number[];
+/** The message the guard prints. Held here so the check and its tests cannot describe it differently. */
+export declare function staleIssueReport(stale: readonly number[]): string;

package/dist/dev/stale-issue-guard.js

@@ -0,0 +1,75 @@
+/**
+ * An issue we have already fixed must not still read as available work.
+ *
+ * Three contributor PRs died on arrival in one week for this. #373 was filed at 09:52 and fixed by
+ * us at 12:33 the same day, then left open for three more days — somebody started on it on day two.
+ * #398 shipped and stayed open; a second contributor rebuilt it from scratch. `GITHUB.md` already
+ * documents the same failure costing three contributors before either of those, which makes this the
+ * third recurrence of a defect we have written down and asked ourselves to remember.
+ *
+ * Remembering is not a mechanism, and this is the smallest one that works: a commit saying it closes
+ * an issue is a claim that the issue is done. If that issue is still open and unlabelled afterwards,
+ * the tracker is lying to whoever reads it next — and the person it lies to is by definition someone
+ * looking for something to work on.
+ *
+ * ## Why `fixed-pending-release` is an accepted answer
+ *
+ * Work fixed on an unreleased branch is legitimately still open; the issue closes when the version
+ * ships. The label is what tells a contributor not to start, so the label — not the closure — is
+ * what this guard is actually asking for. That is also why the fix is cheap: nobody has to change
+ * when they close things, only to say so.
+ *
+ * Pure. The git log and the GitHub lookup belong to the caller, which is what makes every branch
+ * below testable without a network or a repo.
+ */
+/** The label that means "fixed, waiting for a release" — an honest reason to still be open. */
+const PENDING_RELEASE_LABEL = 'fixed-pending-release';
+/**
+ * Issue numbers a commit message CLAIMS to have closed.
+ *
+ * Only the closing verbs GitHub itself acts on. A bare `#447`, a `Refs #447` or a `see #447` is how
+ * a change points at context it did not close — the exact habit we want to encourage — so counting
+ * those would make the guard cry wolf on good behaviour, and a check that cries wolf is one people
+ * learn to skip.
+ */
+const CLOSING_REF = /\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s+#(\d+)/gi;
+export function closedRefsIn(commitMessage) {
+    const seen = new Set();
+    for (const match of commitMessage.matchAll(CLOSING_REF)) {
+        const raw = match[1];
+        if (raw === undefined)
+            continue;
+        const parsed = Number.parseInt(raw, 10);
+        if (Number.isFinite(parsed))
+            seen.add(parsed);
+    }
+    return [...seen];
+}
+/**
+ * Of the issues these commits claimed to close, the ones still reading as available work.
+ *
+ * An issue that could not be looked up is deliberately silent rather than failing. A rate limit, a
+ * transferred issue or a deleted one would otherwise turn this red for a reason unrelated to what it
+ * guards, and a guard that goes red for unrelated reasons gets disabled — which costs more than the
+ * defect it was catching.
+ */
+export function staleIssues(claimed, issues) {
+    const byNumber = new Map(issues.map((issue) => [issue.number, issue]));
+    return claimed.filter((number) => {
+        const issue = byNumber.get(number);
+        if (issue === undefined)
+            return false;
+        if ('closed' === issue.state)
+            return false;
+        return !issue.labels.includes(PENDING_RELEASE_LABEL);
+    });
+}
+/** The message the guard prints. Held here so the check and its tests cannot describe it differently. */
+export function staleIssueReport(stale) {
+    const list = stale.map((n) => `#${String(n)}`).join(', ');
+    return (`${list} ${1 === stale.length ? 'is' : 'are'} still OPEN, and a commit on this branch says it ` +
+        `closes ${1 === stale.length ? 'it' : 'them'}. Anyone browsing the tracker reads that as work ` +
+        `nobody has started. Close ${1 === stale.length ? 'it' : 'them'}, or label ` +
+        `${1 === stale.length ? 'it' : 'them'} \`${PENDING_RELEASE_LABEL}\` if the fix is waiting on a ` +
+        `release. This has cost three contributors an evening each; it is not bookkeeping.`);
+}

package/dist/domain/domain-tools.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
-import { asNumber } from '../tools/tools-helpers.js';
+import { sessionRoot } from '../project/session-root.js';
+import { asNumber, asString } from '../tools/tools-helpers.js';
 import { ReticleTool } from '../tools/tool-names.js';
 import { readContract } from '../project/reticle-dir.js';
 import { buildDomainModel } from './domain-model.js';
@@ -74,7 +75,7 @@ export const DOMAIN_TOOLS = [
                 if (loaded.ok)
                     flows.push(loaded.value);
             }
-            const contract = await readContract(deps.fs, deps.reticleRoot);
+            const contract = await readContract(deps.fs, sessionRoot(deps, asString(args['sessionId'])));
             const project = await deps.project.read();
             const runs = project.ok ? project.file.runs : [];
             const model = buildDomainModel(flows, contract.ok ? contract.capabilities : null, runs);

package/dist/events/contradictions.d.ts

@@ -113,5 +113,46 @@ export interface ContradictionOptions {
      * with no view.
      */
     renderProved?: boolean | undefined;
+    /**
+     * The document currently under observation, as the session derived it from its own event stream.
+     *
+     * Every rule below reasons about "the same window", and a window is scoped by time and by
+     * ring-buffer capacity and by nothing else — so it can still hold the traffic of a page a full
+     * navigation or a reload has already thrown away. Naming that traffic as the cause of an action
+     * taken now is true about the bytes and false about the world.
+     *
+     * Undefined means nobody could say which document is current (an SDK too old to stamp one, a caller
+     * with no session in hand), and the scoping then does nothing at all — `isSameDocument` treats
+     * absence as current on both sides, so the engine behaves exactly as it did before this existed.
+     */
+    currentDocumentId?: string | undefined;
+    /**
+     * The edit epoch currently in force, as the session derived it from its own event stream.
+     *
+     * The edit-shaped half of `currentDocumentId`. A hot update replaces modules and re-renders inside
+     * the SAME document, so the document id cannot see it and observations of code the agent has
+     * already rewritten go on answering for it in silence.
+     *
+     * Undefined means nobody could say (an SDK too old to stamp one, a page with no hot-update channel,
+     * a caller with no session in hand) and the scoping then does nothing at all — `isSameEditEpoch`
+     * treats absence as current on both sides.
+     */
+    currentEditEpoch?: number | undefined;
 }
+/**
+ * Cross-channel contradictions in this window, with the edit-epoch caveat attached when it applies.
+ *
+ * Cross-epoch evidence is LABELLED rather than excluded, which is the opposite of what the document
+ * scoping does, and the difference is the point. A navigation is total — it throws away the page,
+ * the refs, the in-flight requests and the state — so nothing recorded before it is still about the
+ * world, and dropping it is the only honest option. A hot update is not: most modules, most of the
+ * DOM, the whole network log and every console line survive one, so most of what was observed a
+ * second before an edit is still true a second after. Excluding it would empty windows that hold
+ * real findings, and an emptied window reads as "nothing happened" — which is the more expensive of
+ * the two wrong answers and the one this whole family of checks exists to prevent.
+ *
+ * So the findings stand and the caveat is said out loud, and only when it is unambiguous: EVERY
+ * observation in the window predates the edit. One post-edit observation and the agent is already
+ * looking at the code it wrote, so the label would be noise.
+ */
 export declare function findContradictions(allEvents: readonly ReticleEvent[], options?: ContradictionOptions): Contradiction[];

package/dist/events/contradictions.js

@@ -1,4 +1,5 @@
-import { ContradictionKind, EventType, MUTATING_METHODS, isDevToolingUrl, } from '@reticlehq/core';
+import { ContradictionKind, EventType, MUTATING_METHODS, isDevToolingUrl, isSameDocument, isSameEditEpoch, } from '@reticlehq/core';
+import { describeSuperseded } from './observed-in-window.js';
 import { findStaleResponses } from './stale-response.js';
 import { findBodyFailures } from './body-failures.js';
 import { findEchoMismatches } from './echo-mismatch.js';
@@ -162,9 +163,64 @@ function splitDevTooling(events) {
     });
     return { app, ignored };
 }
+/**
+ * Cross-channel contradictions in this window, with the edit-epoch caveat attached when it applies.
+ *
+ * Cross-epoch evidence is LABELLED rather than excluded, which is the opposite of what the document
+ * scoping does, and the difference is the point. A navigation is total — it throws away the page,
+ * the refs, the in-flight requests and the state — so nothing recorded before it is still about the
+ * world, and dropping it is the only honest option. A hot update is not: most modules, most of the
+ * DOM, the whole network log and every console line survive one, so most of what was observed a
+ * second before an edit is still true a second after. Excluding it would empty windows that hold
+ * real findings, and an emptied window reads as "nothing happened" — which is the more expensive of
+ * the two wrong answers and the one this whole family of checks exists to prevent.
+ *
+ * So the findings stand and the caveat is said out loud, and only when it is unambiguous: EVERY
+ * observation in the window predates the edit. One post-edit observation and the agent is already
+ * looking at the code it wrote, so the label would be noise.
+ */
 export function findContradictions(allEvents, options = {}) {
+    const found = findWindowContradictions(allEvents, options);
+    const predates = allEvents.length > 0 &&
+        allEvents.every((e) => !isSameEditEpoch(e.editEpoch, options.currentEditEpoch));
+    if (!predates)
+        return found;
+    // Prepended, not appended: the caveat governs how everything under it should be read, and it has
+    // to survive the rules that return early with a single finding of their own.
+    return [
+        {
+            kind: ContradictionKind.EVIDENCE_PREDATES_EDIT,
+            claim: 'these observations describe the code as it is now',
+            counter: 'every one of them was recorded before the last hot update landed in the page',
+            detail: 'the source changed and the page re-rendered after this evidence was captured, so it describes code that has since been replaced — nothing here is necessarily wrong, but nothing here has seen the edit either. Drive the app again to verify the current code',
+        },
+        ...found,
+    ];
+}
+function findWindowContradictions(allEvents, options) {
     const found = [];
-    const { app: events, ignored: ignoredDevTooling } = splitDevTooling(allEvents);
+    const { app: allApp, ignored: ignoredDevTooling } = splitDevTooling(allEvents);
+    // ── Evidence belonging to a document that has since been replaced ───────────────────────────
+    // Scoped ONCE, here, for the same reason the dev-tooling split is: every rule below asks "what
+    // else was in this window", and answering that with a dead page's traffic is a defect in all of
+    // them rather than in whichever one reported it. Applied after the dev-tooling split so the count
+    // reported below is the app's own evidence and not the toolchain's noise.
+    const events = allApp.filter((e) => isSameDocument(e.documentId, options.currentDocumentId));
+    const superseded = allApp.length - events.length;
+    // An empty window was always allowed to mean "nothing happened"; that reading is only unsafe once
+    // supersession is what emptied it. Reported ALONE and before every rule below, because a window
+    // with nothing left in it is exactly the shape `action-had-no-effect` fires on — so without this
+    // the fix would have swapped a wrong citation for a wrong accusation.
+    if (superseded > 0 && 0 === events.length) {
+        return [
+            {
+                kind: ContradictionKind.EVIDENCE_SUPERSEDED,
+                claim: 'this window holds observations that could answer for the action',
+                counter: describeSuperseded('observations', superseded),
+                detail: 'a full navigation or a reload built a new document, and everything recorded here belongs to the old one — citing it would name requests, errors and state that no longer describe anything on screen',
+            },
+        ];
+    }
     const settled = events.filter((e) => e.type === EventType.NET_REQUEST).map(netCall);
     // ── Overlapping reads that settled out of order ─────────────────────────────────────────────
     // Independent of any action, so it runs on every window: the race is a property of the timeline.
@@ -290,18 +346,71 @@ export function findContradictions(allEvents, options = {}) {
     if (!advanced) {
         const ignoredWrites = settled.filter((c) => true === c.ok && isMutating(c));
         if (ignoredWrites.length > 0) {
-            found.push({
-                kind: ContradictionKind.RESPONSE_IGNORED,
-                claim: `${String(ignoredWrites.length)} write(s) succeeded on the server`,
-                counter: 'nothing on the client changed — no DOM, store or route movement',
-                detail: ignoredWrites.map(describe).join('; '),
-            });
+            // ...unless THIS document handed the consequence to another browsing context. An OAuth sign-in
+            // posts, succeeds, and continues in a popup the in-page SDK cannot follow (#508): the original
+            // tab legitimately never changes, and response-ignored would accuse it of ignoring a response
+            // it handed off. The opened-context event flips the reading from "the client did nothing" to
+            // "the client went where we cannot look". Scoped like every rule here to the attribution floor
+            // (`options.actionSince`; the local below is declared later, for the window rules).
+            const contextFloor = options.actionSince;
+            const openedContext = events.some((e) => e.type === EventType.CONTEXT_OPENED && contextFloor !== undefined && e.t >= contextFloor);
+            found.push(openedContext
+                ? {
+                    kind: ContradictionKind.CONSEQUENCE_ELSEWHERE,
+                    claim: `${String(ignoredWrites.length)} write(s) succeeded on the server`,
+                    counter: 'this document never changed because the page opened another browsing context during this window (e.g. an OAuth popup), where the in-page SDK cannot observe the result',
+                    detail: ignoredWrites.map(describe).join('; '),
+                }
+                : {
+                    kind: ContradictionKind.RESPONSE_IGNORED,
+                    claim: `${String(ignoredWrites.length)} write(s) succeeded on the server`,
+                    counter: 'nothing on the client changed — no DOM, store or route movement',
+                    detail: ignoredWrites.map(describe).join('; '),
+                });
         }
     }
+    // ── The app announced a consequence and nothing else moved ─────────────────────────────────
+    // Scoped as tightly as the evidence allows, because this rule fires on the ABSENCE of everything
+    // else and that is the easiest way to build a false positive.
+    //
+    // Only when the window is otherwise EMPTY: no DOM, no store, no route (`!advanced`) and no request
+    // at all. A request means the app reached for something, and whether it settled, failed or was
+    // ignored belongs to three other rules — firing here too would report one fact twice.
+    //
+    // `successSignals` reuses the failure-shaped filter above: an app that announced `deploy:failed`
+    // is correctly reporting that nothing happened, and accusing it inverts the meaning of the one app
+    // doing this right.
+    //
+    // And only for a window attributed to an ACTION. `reticle_assert` OBSERVES — there is no click
+    // whose consequence should have corroborated anything, so an assert over a quiet window carrying
+    // one signal is an ordinary read, not a claim nothing backs. Without this the rule reddened eight
+    // existing tests that assert exactly that, which is the false-positive class this scoping exists
+    // to prevent.
+    if (options.actionSince !== undefined &&
+        !advanced &&
+        0 === settled.length &&
+        successSignals.length > 0) {
+        found.push({
+            kind: ContradictionKind.SIGNAL_WITHOUT_CONSEQUENCE,
+            claim: `the app fired ${successSignals.map((s) => `"${s}"`).join(', ')}`,
+            counter: 'nothing else in the window moved — no DOM, no store, no route, no request — so the only ' +
+                'evidence that anything happened is the app saying so',
+            detail: 'a signal emitted from the value the app was ASKED for, rather than the one it committed, ' +
+                'reads identically to one that worked',
+        });
+    }
     // ── The same write fired more than once, inside ONE action's window ─────────────────────────
     // Attribution is the whole rule here, not a refinement of it: counting `method + url` over whatever
     // window the caller handed in turns two legitimate separate saves into a double submit. See
     // ContradictionOptions.actionSince.
+    //
+    // A captured request body joins the identity. A command-bus API posts every mutation to one URL
+    // and discriminates on a body field (`{"command":"study.stage.set"}` vs `{"command":"mesh.plan"}`),
+    // so under URL alone each of those distinct writes read as a repeat of the first, and clean
+    // verdicts degraded to unknown behind doubles that were never doubles. When no body was captured
+    // (capture off, or a non-text body, which reports a type marker instead) there is nothing to
+    // compare and the URL alone stands, as before; a window where only some calls carried bodies
+    // compares nothing rather than guess.
     const actionSince = options.actionSince;
     if (actionSince !== undefined) {
         const writeCounts = new Map();
@@ -311,17 +420,21 @@ export function findContradictions(allEvents, options = {}) {
             const call = netCall(event);
             if (!isMutating(call))
                 continue;
-            const key = `${call.method} ${call.url}`;
-            writeCounts.set(key, (writeCounts.get(key) ?? 0) + 1);
+            const label = `${call.method} ${call.url}`;
+            const body = asString(event.data['requestBody']);
+            const key = body === undefined || 0 === body.length ? label : `${label} ${body}`;
+            const entry = writeCounts.get(key) ?? { label, count: 0 };
+            entry.count += 1;
+            writeCounts.set(key, entry);
         }
-        for (const [key, count] of writeCounts) {
+        for (const [, { label, count }] of writeCounts) {
             if (count < 2)
                 continue;
             found.push({
                 kind: ContradictionKind.DUPLICATE_REQUEST,
                 claim: 'one user action was performed',
                 counter: `the same write fired ${String(count)} times`,
-                detail: `${key} ×${String(count)}`,
+                detail: `${label} ×${String(count)}`,
             });
         }
     }

package/dist/events/declared.d.ts

@@ -31,6 +31,20 @@ export interface DeclaredExpectations {
     rendersContent: boolean;
 }
 export declare function declaredExpectations(predicate: Predicate | undefined): DeclaredExpectations;
+/**
+ * Did the caller name a consequence that does not depend on the response body?
+ *
+ * The unread-body clause exists for the case where the body is the ONLY channel that could have
+ * contradicted the screen — a 200 with per-item failures inside, a GraphQL error that is also a
+ * 200. A declared string on screen, store path, or signal that held is a different channel, and
+ * grading `unknown` there costs a real verdict (measured: a 201 plus the unique row, unread body,
+ * agent went to enable capture instead of finishing the drive).
+ *
+ * Same conservatism as `declaredExpectations`: only the top level and `allOf`. An `anyOf` branch
+ * may never have held, and honouring it would skip the unread caveat on the strength of a net
+ * success that was the branch that actually matched.
+ */
+export declare function declaresBodyIndependentChannel(predicate: Predicate | undefined): boolean;
 /**
  * Does a call the window recorded match a failure the caller declared?
  *

package/dist/events/declared.js

@@ -53,6 +53,39 @@ export function declaredExpectations(predicate) {
         walk(predicate);
     return { netFailures, rendersContent };
 }
+/**
+ * Did the caller name a consequence that does not depend on the response body?
+ *
+ * The unread-body clause exists for the case where the body is the ONLY channel that could have
+ * contradicted the screen — a 200 with per-item failures inside, a GraphQL error that is also a
+ * 200. A declared string on screen, store path, or signal that held is a different channel, and
+ * grading `unknown` there costs a real verdict (measured: a 201 plus the unique row, unread body,
+ * agent went to enable capture instead of finishing the drive).
+ *
+ * Same conservatism as `declaredExpectations`: only the top level and `allOf`. An `anyOf` branch
+ * may never have held, and honouring it would skip the unread caveat on the strength of a net
+ * success that was the branch that actually matched.
+ */
+export function declaresBodyIndependentChannel(predicate) {
+    if (predicate === undefined)
+        return false;
+    const walk = (p) => {
+        switch (p.kind) {
+            case PredicateKind.ALL_OF:
+                return p.predicates.some(walk);
+            case PredicateKind.TEXT:
+                return true !== p.absent;
+            case PredicateKind.SIGNAL:
+            case PredicateKind.STATE:
+                return true;
+            case PredicateKind.ELEMENT:
+                return true !== p.absent && (p.query.value !== undefined || p.query.text !== undefined);
+            default:
+                return false;
+        }
+    };
+    return walk(predicate);
+}
 /**
  * Does a call the window recorded match a failure the caller declared?
  *

package/dist/events/echo-mismatch.js

@@ -133,6 +133,20 @@ export function findEchoMismatches(events, actionSince) {
             continue;
         const echoed = scalarsByKey(response);
         const asked = scalarsByKey(request);
+        // The response has to be ECHO-SHAPED before any key can contradict anything. An echo restates
+        // what was sent, so most of the request's scalar keys reappear somewhere in it; a snapshot that
+        // happens to share a key or two does not (#506: `{"command":"chat.send"}` answered with the
+        // viewer snapshot read one incidental shared key as an attempted echo of a write that fully
+        // applied). Requiring a strict majority of the request's keys to appear keeps every documented
+        // true positive — an envelope restates most of its fields — and deliberately trades the rare
+        // half-echoed write away, the same direction MAX_ECHO_KEYS already trades in.
+        let shared = 0;
+        for (const key of asked.keys()) {
+            if (echoed.has(key))
+                shared += 1;
+        }
+        if (shared * 2 <= asked.size)
+            continue;
         const dropped = [];
         for (const [key, wanted] of asked) {
             // More than one requested value for a key (a before/after pair, a list of items) makes "what

package/dist/events/observed-in-window.d.ts

@@ -10,3 +10,15 @@
  * not do what you thought) versus things happened but not that one (you named it wrong).
  */
 export declare function describeObserved(noun: string, seen: readonly string[]): string;
+/**
+ * The third answer, and the one this file existed to make room for: things happened, and they belong
+ * to a document that has since been replaced.
+ *
+ * `describeObserved` already separates "nothing happened" from "things happened but not that one",
+ * because those need different fixes. A window whose evidence was discarded as superseded is a third
+ * case needing a third fix, and it is the one that reads most like the first: everything that could
+ * have answered the question is gone, so a bare "nothing happened in this window" is available and
+ * wrong. The remedy is in the sentence, because an agent that cannot act on a caveat learns to skip
+ * it — here the remedy is to drive the action again against the page now on screen.
+ */
+export declare function describeSuperseded(noun: string, count: number): string;

package/dist/events/observed-in-window.js

@@ -19,3 +19,20 @@ export function describeObserved(noun, seen) {
     const rest = unique.length - shown.length;
     return `${noun} seen in this window: ${shown.join(', ')}${rest > 0 ? `, and ${String(rest)} more` : ''}`;
 }
+/**
+ * The third answer, and the one this file existed to make room for: things happened, and they belong
+ * to a document that has since been replaced.
+ *
+ * `describeObserved` already separates "nothing happened" from "things happened but not that one",
+ * because those need different fixes. A window whose evidence was discarded as superseded is a third
+ * case needing a third fix, and it is the one that reads most like the first: everything that could
+ * have answered the question is gone, so a bare "nothing happened in this window" is available and
+ * wrong. The remedy is in the sentence, because an agent that cannot act on a caveat learns to skip
+ * it — here the remedy is to drive the action again against the page now on screen.
+ */
+export function describeSuperseded(noun, count) {
+    return (`no ${noun} belong to the document currently on screen: ${String(count)} ${noun} were observed ` +
+        `and every one of them belongs to a document that has since been replaced (the page reloaded or ` +
+        `navigated). This says nothing about the app — the evidence went away with the page that produced ` +
+        `it. Re-drive the action against the page now on screen`);
+}

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

@@ -0,0 +1,30 @@
+import type { Predicate } from './predicate-schema.js';
+/**
+ * Did the caller's predicate ask about registered state?
+ *
+ * Walks composites, because `allOf[{net}, {state}]` asks about state exactly as much as a bare
+ * `{state}` does — and the gap that reveals is the same one either way.
+ *
+ * Lives here rather than at a call site because both the act path and the assert path need it, and
+ * two walkers over one predicate tree is two chances to disagree about what counts as asking.
+ *
+ * NOT in `predicate-schema.ts` next to `predicateFieldsFor`, where it would otherwise belong: five
+ * open contributor PRs are queued on that file and on `predicate-eval.ts`, and a one-function import
+ * is not worth handing five people a conflict. Named `predicate-asks` rather than `predicate-shape`
+ * because `predicate-shape.test.ts` already exists and is about something else entirely — a file
+ * that reads as the subject of an unrelated test is a half-hour somebody loses later.
+ */
+export declare function declaresState(predicate: Predicate): boolean;
+/**
+ * Does the caller's predicate judge the DOM — an `element` or `text` clause anywhere in the tree?
+ *
+ * The question behind it is where a verdict is allowed to point. A DOM predicate has its own locus:
+ * the element it matched, whose `file:line` the descriptor already carries. A `signal`/`net`/`state`
+ * failure has none — there is no node for "the request was never made" — and that is the one case
+ * where the verdict borrows the last driven control's line, because the handler that should have
+ * fired lives there.
+ *
+ * Walks composites for the same reason `declaresState` does: `allOf[{element}, {signal}]` looked at
+ * the DOM exactly as much as a bare `{element}` did.
+ */
+export declare function declaresDom(predicate: Predicate): boolean;

package/dist/events/predicate-asks.js

@@ -0,0 +1,48 @@
+import { PredicateKind } from '@reticlehq/core';
+/**
+ * Did the caller's predicate ask about registered state?
+ *
+ * Walks composites, because `allOf[{net}, {state}]` asks about state exactly as much as a bare
+ * `{state}` does — and the gap that reveals is the same one either way.
+ *
+ * Lives here rather than at a call site because both the act path and the assert path need it, and
+ * two walkers over one predicate tree is two chances to disagree about what counts as asking.
+ *
+ * NOT in `predicate-schema.ts` next to `predicateFieldsFor`, where it would otherwise belong: five
+ * open contributor PRs are queued on that file and on `predicate-eval.ts`, and a one-function import
+ * is not worth handing five people a conflict. Named `predicate-asks` rather than `predicate-shape`
+ * because `predicate-shape.test.ts` already exists and is about something else entirely — a file
+ * that reads as the subject of an unrelated test is a half-hour somebody loses later.
+ */
+export function declaresState(predicate) {
+    if (predicate.kind === PredicateKind.STATE)
+        return true;
+    if (predicate.kind === PredicateKind.ALL_OF || predicate.kind === PredicateKind.ANY_OF) {
+        return predicate.predicates.some(declaresState);
+    }
+    if (predicate.kind === PredicateKind.NOT)
+        return declaresState(predicate.predicate);
+    return false;
+}
+/**
+ * Does the caller's predicate judge the DOM — an `element` or `text` clause anywhere in the tree?
+ *
+ * The question behind it is where a verdict is allowed to point. A DOM predicate has its own locus:
+ * the element it matched, whose `file:line` the descriptor already carries. A `signal`/`net`/`state`
+ * failure has none — there is no node for "the request was never made" — and that is the one case
+ * where the verdict borrows the last driven control's line, because the handler that should have
+ * fired lives there.
+ *
+ * Walks composites for the same reason `declaresState` does: `allOf[{element}, {signal}]` looked at
+ * the DOM exactly as much as a bare `{element}` did.
+ */
+export function declaresDom(predicate) {
+    if (predicate.kind === PredicateKind.ELEMENT || predicate.kind === PredicateKind.TEXT)
+        return true;
+    if (predicate.kind === PredicateKind.ALL_OF || predicate.kind === PredicateKind.ANY_OF) {
+        return predicate.predicates.some(declaresDom);
+    }
+    if (predicate.kind === PredicateKind.NOT)
+        return declaresDom(predicate.predicate);
+    return false;
+}