@reticlehq/server 2.11.0 → 2.12.0

package/dist/cloud/cloud-sync.js

@@ -30,6 +30,38 @@ export function resolveCloudConfig(env) {
         return null;
     return { url: url.replace(/\/+$/, ''), apiKey };
 }
+/**
+ * Budget for a cloud call. Node's `fetch` has NO default timeout, so a connection that opens and then
+ * stalls never settles — and the caller `await`s it forever. In `reticle_flow_verify` that is an MCP
+ * tool call that never returns, and in `reticle cloud …` a terminal that prints nothing.
+ *
+ * One shared budget covers every call here: they are all small JSON request/response pairs against the
+ * same API, so there is nothing to tune per site. The ONE exception is the hosted verification submit,
+ * which blocks while a real browser runs the suite server-side — a normal response there is minutes,
+ * not seconds, so it gets its own (still bounded) budget rather than dragging the common one up.
+ */
+const CLOUD_FETCH_TIMEOUT_MS = 30_000;
+export const CLOUD_VERIFY_TIMEOUT_MS = 120_000;
+/** Names Node gives an abort: `AbortSignal.timeout` raises TimeoutError, an explicit abort AbortError. */
+const TIMEOUT_ERROR_NAMES = new Set(['TimeoutError', 'AbortError']);
+/**
+ * The fetch every cloud call goes through. Adds the abort signal, and turns the abort into a message
+ * that says what happened and what to do — a bare `AbortError` reaching a user or an agent is a riddle,
+ * and the agent-facing half of this product is judged on whether its errors are actionable.
+ */
+export async function cloudFetch(url, init, timeoutMs = CLOUD_FETCH_TIMEOUT_MS) {
+    try {
+        return await fetch(url, { ...init, signal: AbortSignal.timeout(timeoutMs) });
+    }
+    catch (err) {
+        if (err instanceof Error && TIMEOUT_ERROR_NAMES.has(err.name)) {
+            throw new Error(`Reticle Cloud request timed out after ${Math.round(timeoutMs / 1000)}s: ${init.method} ${url}. ` +
+                `The server accepted the connection but never answered. Check the network and ${CloudEnv.URL}, then retry — ` +
+                `verification works locally without cloud.`);
+        }
+        throw err;
+    }
+}
 export const SyncOutcome = {
     SYNCED: 'synced',
     SKIPPED: 'skipped',

package/dist/crawl/crawl.d.ts

@@ -4,6 +4,15 @@ export interface CrawlSession {
     command(name: string, args?: Record<string, unknown>): Promise<CommandResult>;
     elapsed(): number;
     eventsSince(cursor: number): ReticleEvent[];
+    /**
+     * Which document is on screen now, so a finding is never drawn from a page the crawl has already
+     * navigated away from. Optional for the same reason `beginAction` is: a test fake supplies a
+     * minimal session, and its absence leaves the scoping inert rather than broken.
+     */
+    readonly currentDocumentId?: string | undefined;
+    /** Which round of source edits is in force, so a finding drawn entirely from pre-edit evidence
+     *  says so. Optional for the same reason `currentDocumentId` is. */
+    readonly currentEditEpoch?: number | undefined;
     /**
      * Attribution window around each click. Optional so a caller can supply a minimal session, but a real
      * session MUST provide it: without a window the click's own effects carry no actionId, and an
@@ -44,19 +53,6 @@ export interface CrawlAnomaly {
 }
 /** Said out loud when the page was larger than one snapshot, so a clean sweep cannot mean "all clear". */
 export declare const CAPPED_SNAPSHOT_NOTE = "the page exceeded one snapshot, so controls past the cap were never seen \u2014 interactiveFound is a floor, not a total; re-run with a narrower `scope` to cover the rest";
-/**
- * Said out loud when the crawl's OWN clicks put controls on the page that it then never visited.
- *
- * The enumeration happens once, before the first click, so a control that only exists after a login,
- * a modal or a tab switch is invisible to this run. Measured on the bench app: a crawl of the login
- * screen visited three controls, its click on "Sign in" produced seven more, and it returned
- * `truncated: false` with an empty anomaly list and nine of twelve steps unused. Read as a sweep,
- * that is a clean bill of health for an app the crawl never entered.
- *
- * The same words as the capped-snapshot case on purpose — it is the same idea (interactiveFound is a
- * floor) reached by a different route, and a second vocabulary for it would just be more to learn.
- */
-export declare function revealedControlsNote(count: number): string;
 export interface CrawlReport {
     interactiveFound: number;
     stepsRun: number;

package/dist/crawl/crawl.js

@@ -18,7 +18,7 @@ export const CAPPED_SNAPSHOT_NOTE = 'the page exceeded one snapshot, so controls
  * The same words as the capped-snapshot case on purpose — it is the same idea (interactiveFound is a
  * floor) reached by a different route, and a second vocabulary for it would just be more to learn.
  */
-export function revealedControlsNote(count) {
+function revealedControlsNote(count) {
     return (`the page changed as you clicked: ${String(count)} control(s) that did not exist when this crawl ` +
         'started were never visited — interactiveFound is a floor, not a total; re-run the crawl from ' +
         'the state you are now in to cover them');
@@ -65,7 +65,19 @@ export function legitimatelyInert(desc) {
         return true;
     if (desc.includes('[checked]'))
         return true;
-    return /\b(textbox|searchbox|combobox|spinbutton)\b/.test(desc);
+    // Inputs, and the ARIA LIVE-REGION roles.
+    //
+    // `alert`, `status`, `log`, `timer` and `marquee` exist to be READ — a screen reader announces
+    // them and nothing is meant to happen when one is clicked. Clicking twice and seeing nothing is
+    // therefore correct behaviour, and reporting it as `dead-control` accuses a working app.
+    //
+    // Found by driving a real app: the demo reported `dead-control — alert "Invalid email or
+    // password"`, which is a login form correctly telling somebody their password was wrong. That is
+    // the most expensive kind of false positive there is — the strongest claim the crawler makes,
+    // about an app that was working, and on the path a new user meets first.
+    //
+    // `alertdialog` is deliberately NOT here: it is interactive, and a word boundary keeps it out.
+    return /\b(textbox|searchbox|combobox|spinbutton|alert|status|log|timer|marquee)\b/.test(desc);
 }
 /**
  * How many interactive controls exist now that did not exist when the crawl enumerated.
@@ -199,7 +211,12 @@ export async function crawl(session, opts, sleep) {
         }
         // CONTRADICTIONS: the channels disagree about what this click did. Reported per control, so a
         // crawl of an unknown app surfaces its false greens without anyone knowing where to look.
-        for (const c of findContradictions(events)) {
+        // A crawl clicks controls that navigate, so its windows are the ones most likely to straddle a
+        // document boundary — and a finding here is reported against a specific control by name.
+        for (const c of findContradictions(events, {
+            currentDocumentId: session.currentDocumentId,
+            currentEditEpoch: session.currentEditEpoch,
+        })) {
             counts.contradictions += 1;
             anomalies.push({
                 kind: c.kind,

package/dist/daemon/daemon-resolve.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Which daemon does THIS project belong to?
+ *
+ * The system answered that two incompatible ways. Build plugins asked the registry by projectId, the
+ * way `pickDaemonPort` was designed to be asked. The CLI and the MCP proxy asked a NUMBER —
+ * `envPort ?? projectPort ?? 4400` — and then attached to whatever owned it, whoever it belonged to.
+ *
+ * So every project on a machine funnelled into one daemon. Its recorded identity was whichever
+ * project won the race to the port, which made the registry entry wrong the moment a second project
+ * attached, and made one `kill` on one well-known port a machine-wide outage for every agent at once.
+ *
+ * It worked anyway, by luck: everyone defaulted to the same number, so everyone found each other.
+ * The luck ends the moment a daemon is anywhere but the default — which is exactly when discovery was
+ * supposed to help, and exactly when it returned nothing.
+ *
+ * This module is the one answer both sides now use. It is pure and injectable: no process spawning,
+ * no port binding, nothing that needs a real `~/.reticle` to test.
+ */
+import { type DaemonRegistryEntry } from '@reticlehq/core';
+/**
+ * Every well-formed registry entry in `home`.
+ *
+ * A corrupt or half-written entry is skipped rather than thrown on: the registry is written by other
+ * processes that can be killed mid-write, and one bad file must not make a machine's daemons
+ * undiscoverable. Validated through core's schema so a shape change cannot silently pass here.
+ */
+export declare function readDaemonRegistry(home: string): DaemonRegistryEntry[];
+/**
+ * The port of the live daemon serving `projectId`, or undefined when this project has none.
+ *
+ * Undefined means "start one", never "use the default and hope". That distinction is the fix: the old
+ * path had no way to express "no daemon of mine exists", so it fell through to a number and attached
+ * to a stranger.
+ *
+ * The selection rule is core's `pickDaemonPort`, shared with every build plugin, so the daemon side
+ * and the app side cannot disagree about which daemon is ours.
+ */
+export declare function resolveDaemonForProject(projectId: string | undefined, home: string, alive: (pid: number) => boolean): number | undefined;
+/**
+ * May `caller` take over a daemon already sitting on the port it wanted?
+ *
+ * Two deliberate escape hatches, both of which keep an existing install working:
+ *
+ * A daemon that claims NO project was started somewhere without a `.reticle.json` — the global MCP
+ * registration in a directory that is not an app, which is the majority of daemons in the field. It
+ * belongs to nobody, so it belongs to whoever asks; refusing would break every user running Reticle
+ * globally, which is how it is documented to be installed.
+ *
+ * A caller with no project of its own has no identity to defend and nothing to be confused about, so
+ * it keeps the old permissive behaviour rather than being locked out of a daemon it can use.
+ *
+ * Everything else — a named daemon and a differently-named caller — is the cross-project bleed, and
+ * is the one case this refuses.
+ */
+export declare function adoptable(daemonProjectId: string | undefined, callerProjectId: string | undefined): boolean;
+/** The project a daemon on `port` claims, or undefined when it claims none / is not registered. */
+export declare function daemonProjectAt(port: number, home: string): string | undefined;
+/**
+ * The port this agent's MCP proxy should serve, decided BEFORE the proxy starts.
+ *
+ * Resolved once rather than per reconnect because the proxy's transport is built around a fixed
+ * number, and making it chase a moving port would mean reworking the reconnect path — the one piece
+ * of this system whose failure mode is "the MCP server disappeared mid-session". The port it settles
+ * on is this project's own, so the thing it would be chasing is a daemon it alone is responsible for.
+ *
+ * The order is the whole fix:
+ *   1. our project's live daemon, wherever it is listening — a daemon that moved is still ours;
+ *   2. the preferred port, but only if free or holding a daemon we may adopt;
+ *   3. a port the OS gives us, when the preferred one belongs to somebody else.
+ *
+ * Step 3 is what stops a second project from attaching to the first project's daemon. That single
+ * silent adoption is what made every agent on a machine share one process, one identity and one
+ * blast radius.
+ */
+export declare function resolveMcpPort(preferred: number, projectId: string | undefined, home: string, deps: {
+    alive: (pid: number) => boolean;
+    daemonPresent: (port: number) => Promise<boolean>;
+    pickPort: (preferred: number) => Promise<number>;
+}): Promise<number>;

package/dist/daemon/daemon-resolve.js

@@ -0,0 +1,118 @@
+/**
+ * Which daemon does THIS project belong to?
+ *
+ * The system answered that two incompatible ways. Build plugins asked the registry by projectId, the
+ * way `pickDaemonPort` was designed to be asked. The CLI and the MCP proxy asked a NUMBER —
+ * `envPort ?? projectPort ?? 4400` — and then attached to whatever owned it, whoever it belonged to.
+ *
+ * So every project on a machine funnelled into one daemon. Its recorded identity was whichever
+ * project won the race to the port, which made the registry entry wrong the moment a second project
+ * attached, and made one `kill` on one well-known port a machine-wide outage for every agent at once.
+ *
+ * It worked anyway, by luck: everyone defaulted to the same number, so everyone found each other.
+ * The luck ends the moment a daemon is anywhere but the default — which is exactly when discovery was
+ * supposed to help, and exactly when it returned nothing.
+ *
+ * This module is the one answer both sides now use. It is pure and injectable: no process spawning,
+ * no port binding, nothing that needs a real `~/.reticle` to test.
+ */
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { DaemonRegistryEntrySchema, daemonRegistryPort, pickDaemonPort, } from '@reticlehq/core';
+/**
+ * Every well-formed registry entry in `home`.
+ *
+ * A corrupt or half-written entry is skipped rather than thrown on: the registry is written by other
+ * processes that can be killed mid-write, and one bad file must not make a machine's daemons
+ * undiscoverable. Validated through core's schema so a shape change cannot silently pass here.
+ */
+export function readDaemonRegistry(home) {
+    let files;
+    try {
+        files = readdirSync(home);
+    }
+    catch {
+        return []; // no ~/.reticle yet: no daemon has ever run here
+    }
+    const entries = [];
+    for (const file of files) {
+        if (null === daemonRegistryPort(file))
+            continue;
+        try {
+            const parsed = DaemonRegistryEntrySchema.safeParse(JSON.parse(readFileSync(join(home, file), 'utf8')));
+            if (parsed.success)
+                entries.push(parsed.data);
+        }
+        catch {
+            continue;
+        }
+    }
+    return entries;
+}
+/**
+ * The port of the live daemon serving `projectId`, or undefined when this project has none.
+ *
+ * Undefined means "start one", never "use the default and hope". That distinction is the fix: the old
+ * path had no way to express "no daemon of mine exists", so it fell through to a number and attached
+ * to a stranger.
+ *
+ * The selection rule is core's `pickDaemonPort`, shared with every build plugin, so the daemon side
+ * and the app side cannot disagree about which daemon is ours.
+ */
+export function resolveDaemonForProject(projectId, home, alive) {
+    return pickDaemonPort(readDaemonRegistry(home), projectId, alive) ?? undefined;
+}
+/**
+ * May `caller` take over a daemon already sitting on the port it wanted?
+ *
+ * Two deliberate escape hatches, both of which keep an existing install working:
+ *
+ * A daemon that claims NO project was started somewhere without a `.reticle.json` — the global MCP
+ * registration in a directory that is not an app, which is the majority of daemons in the field. It
+ * belongs to nobody, so it belongs to whoever asks; refusing would break every user running Reticle
+ * globally, which is how it is documented to be installed.
+ *
+ * A caller with no project of its own has no identity to defend and nothing to be confused about, so
+ * it keeps the old permissive behaviour rather than being locked out of a daemon it can use.
+ *
+ * Everything else — a named daemon and a differently-named caller — is the cross-project bleed, and
+ * is the one case this refuses.
+ */
+export function adoptable(daemonProjectId, callerProjectId) {
+    if (daemonProjectId === undefined || 0 === daemonProjectId.length)
+        return true;
+    if (callerProjectId === undefined || 0 === callerProjectId.length)
+        return true;
+    return daemonProjectId === callerProjectId;
+}
+/** The project a daemon on `port` claims, or undefined when it claims none / is not registered. */
+export function daemonProjectAt(port, home) {
+    return readDaemonRegistry(home).find((e) => e.port === port)?.projectId;
+}
+/**
+ * The port this agent's MCP proxy should serve, decided BEFORE the proxy starts.
+ *
+ * Resolved once rather than per reconnect because the proxy's transport is built around a fixed
+ * number, and making it chase a moving port would mean reworking the reconnect path — the one piece
+ * of this system whose failure mode is "the MCP server disappeared mid-session". The port it settles
+ * on is this project's own, so the thing it would be chasing is a daemon it alone is responsible for.
+ *
+ * The order is the whole fix:
+ *   1. our project's live daemon, wherever it is listening — a daemon that moved is still ours;
+ *   2. the preferred port, but only if free or holding a daemon we may adopt;
+ *   3. a port the OS gives us, when the preferred one belongs to somebody else.
+ *
+ * Step 3 is what stops a second project from attaching to the first project's daemon. That single
+ * silent adoption is what made every agent on a machine share one process, one identity and one
+ * blast radius.
+ */
+export async function resolveMcpPort(preferred, projectId, home, deps) {
+    const mine = resolveDaemonForProject(projectId, home, deps.alive);
+    if (mine !== undefined)
+        return mine;
+    if (!(await deps.daemonPresent(preferred)))
+        return preferred;
+    return adoptable(daemonProjectAt(preferred, home), projectId)
+        ? preferred
+        : deps.pickPort(preferred);
+}

package/dist/daemon/free-port.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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.
+ */
+/** Can we bind `port` on the loopback interface right now? */
+export declare function portIsFree(port: number, host?: string): Promise<boolean>;
+/** Ask the kernel for a free port. Rejects only if the machine cannot bind loopback at all. */
+export declare function osAssignedPort(host?: string): Promise<number>;
+/**
+ * `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 declare function pickDaemonPortToBind(preferred: number, isFree?: (port: number) => Promise<boolean>, assign?: () => Promise<number>): Promise<number>;

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

@@ -27,8 +27,6 @@ export interface IssueState {
     state: 'open' | 'closed';
     labels: readonly string[];
 }
-/** The label that means "fixed, waiting for a release" — an honest reason to still be open. */
-export declare const PENDING_RELEASE_LABEL = "fixed-pending-release";
 export declare function closedRefsIn(commitMessage: string): number[];
 /**
  * Of the issues these commits claimed to close, the ones still reading as available work.

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

@@ -23,7 +23,7 @@
  * below testable without a network or a repo.
  */
 /** The label that means "fixed, waiting for a release" — an honest reason to still be open. */
-export const PENDING_RELEASE_LABEL = 'fixed-pending-release';
+const PENDING_RELEASE_LABEL = 'fixed-pending-release';
 /**
  * Issue numbers a commit message CLAIMS to have closed.
  *

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[];