@reticlehq/server 2.2.0 → 2.3.0

package/dist/daemon-resilience.js

@@ -8,16 +8,78 @@
  * per Node's guidance, so LOG a clear reason and exit cleanly; the next `reticle mcp` respawns a fresh
  * daemon, which beats crashing silently or limping along corrupt.
  */
+import { TelemetryActor, TelemetryEventKind } from '@reticlehq/core';
+import { errorSkeleton, errorTypeOf, fingerprintCrash, MAX_REPORTED_FRAMES, reticleFrames, } from './telemetry/error-fingerprint.js';
+import { getSessionMetrics } from './telemetry/session-metrics.js';
+import { machineSnapshot } from './telemetry/machine-snapshot.js';
+import { getTelemetry } from './telemetry/telemetry.js';
 function describe(value) {
     return value instanceof Error ? value.message : String(value);
 }
+/** The two ways a failure reaches the top of the process. Named so the analytics can tell them apart. */
+export const CrashKind = {
+    UNHANDLED_REJECTION: 'unhandled_rejection',
+    UNCAUGHT_EXCEPTION: 'uncaught_exception',
+};
+/**
+ * Report a crash with enough detail to actually diagnose it.
+ *
+ * This is the only place in the product that learns about a crash at all. An uncaught exception in a
+ * long-running daemon takes down every agent attached to it, and the only other record is a line in a
+ * local log nobody sends us.
+ *
+ * The first version sent a hash and nothing else, which made crashes rankable and undiagnosable — you
+ * could see that forty machines hit `a3f2c1d8e9b0` and had no way to learn what that was. So it now
+ * carries the four things an RCA needs: WHERE (our own frames, with function names and line numbers),
+ * WHAT (the message with every variable part stripped), WHEN (the tool in flight), and WHY-ish (the
+ * agent's approach run before it). All of it is our code and our vocabulary; the user's stack frames,
+ * their paths, and the contents of their message are removed before any of it is built.
+ *
+ * Best-effort and wrapped: reporting a crash must never be the reason a crash gets worse.
+ */
+function reportCrash(kind, value) {
+    try {
+        const errorType = errorTypeOf(value);
+        const stack = value instanceof Error ? (value.stack ?? '') : '';
+        const message = describe(value);
+        const { breadcrumb, inFlight } = getSessionMetrics().trail;
+        const machine = machineSnapshot();
+        void getTelemetry().emit(TelemetryEventKind.RUNTIME_CRASHED, {
+            // A crash is ALWAYS reached through something the agent asked for — the daemon does nothing on
+            // its own — so attributing it to the agent is accurate rather than a guess.
+            actor: TelemetryActor.AGENT,
+            crash: {
+                kind,
+                errorType,
+                fingerprint: fingerprintCrash(errorType, stack, message),
+                // The skeleton, not the message: every quoted string, path, URL, id and number is replaced
+                // by `*` first. This is what makes the fingerprint mean something to a human reading a chart.
+                message: errorSkeleton(message).slice(0, 300),
+                // Our own frames, our own published code. The file, the line, and the function — which is the
+                // whole of "where did it break". Frames from the user's app never survive this.
+                frames: reticleFrames(stack).slice(0, MAX_REPORTED_FRAMES),
+                ...(inFlight !== undefined ? { tool: inFlight } : {}),
+                ...(breadcrumb.length > 0 ? { breadcrumb } : {}),
+                // Crashes cluster hard by runtime version and architecture, and we were recording neither.
+                nodeVersion: process.versions.node,
+                arch: process.arch,
+                // "Out of memory" and "our bug" look identical in a stack trace. This is what tells them apart.
+                ...(machine !== undefined ? { machine } : {}),
+            },
+        });
+    }
+    catch {
+        /* a crash report must never be the reason a crash gets worse */
+    }
+}
 export function installDaemonResilience(proc, log, onFatal) {
     proc.on('unhandledRejection', (reason) => {
         log('reticle_daemon_unhandled_rejection', { reason: describe(reason) });
+        reportCrash(CrashKind.UNHANDLED_REJECTION, reason);
     });
     proc.on('uncaughtException', (err) => {
         log('reticle_daemon_uncaught_exception', { error: describe(err) });
+        reportCrash(CrashKind.UNCAUGHT_EXCEPTION, err);
         onFatal();
     });
 }
-//# sourceMappingURL=daemon-resilience.js.map

package/dist/daemon.d.ts

@@ -1,5 +1,5 @@
 export declare function logPath(port: number): string;
-export declare function readPid(port: number): number | null;
+export declare function readPid(port: number, home?: string): number | null;
 export declare function isAlive(pid: number): boolean;
 export declare function writePid(port: number): void;
 /**
@@ -41,10 +41,30 @@ export declare function discoverDaemonPort(): number | null;
  * ~/.reticle and the process.kill(pid,0) liveness probe).
  */
 export declare function reclaimStaleDaemons(home?: string, pidAlive?: (pid: number) => boolean): number[];
+/** The minimal shape of a spawned child that spawnDaemon uses. */
+export interface SpawnedChild {
+    readonly pid?: number | undefined;
+    on(event: string, handler: (...args: unknown[]) => void): unknown;
+    unref(): void;
+}
+/** Injectable deps for spawnDaemon — the testability seam. Defaults to the real implementations. */
+export interface SpawnDaemonDeps {
+    readonly home: string;
+    openFile(path: string, flags: string): number;
+    closeFile(fd: number): void;
+    spawnChild(command: string, args: readonly string[], options: {
+        detached: boolean;
+        stdio: readonly ('ignore' | number)[];
+    }): SpawnedChild;
+    pidAlive(pid: number): boolean;
+}
+export declare function defaultSpawnDaemonDeps(): SpawnDaemonDeps;
 /**
  * Spawn the reticle daemon as a detached background process, redirecting output to the log file.
  * Writes the PID file from the parent before returning so callers can call isRunning
  * immediately without a race window.
+ *
+ * `deps` is injectable for testing (default: real fs/spawn against ~/.reticle). The same seam
+ * pattern as reclaimStaleDaemons(home, pidAlive).
  */
-export declare function spawnDaemon(nodeExec: string, scriptPath: string, args: string[], port: number): boolean;
-//# sourceMappingURL=daemon.d.ts.map
+export declare function spawnDaemon(nodeExec: string, scriptPath: string, args: string[], port: number, deps?: SpawnDaemonDeps): boolean;

package/dist/daemon.js

@@ -4,8 +4,8 @@ import { mkdirSync, readFileSync, writeFileSync, existsSync, unlinkSync, openSyn
 import { spawn } from 'node:child_process';
 import { daemonRegistryFileName, daemonRegistryPort, DaemonRegistryEntrySchema, pickDaemonPort, } from '@reticlehq/core';
 const RETICLE_HOME = join(homedir(), '.reticle');
-function pidPath(port) {
-    return join(RETICLE_HOME, `daemon-${port}.pid`);
+function pidPath(port, home = RETICLE_HOME) {
+    return join(home, `daemon-${port}.pid`);
 }
 function registryPath(port) {
     return join(RETICLE_HOME, daemonRegistryFileName(port));
@@ -13,8 +13,8 @@ function registryPath(port) {
 export function logPath(port) {
     return join(RETICLE_HOME, `daemon-${port}.log`);
 }
-export function readPid(port) {
-    const path = pidPath(port);
+export function readPid(port, home = RETICLE_HOME) {
+    const path = pidPath(port, home);
     if (!existsSync(path))
         return null;
     const n = parseInt(readFileSync(path, 'utf8').trim(), 10);
@@ -180,43 +180,100 @@ export function reclaimStaleDaemons(home = RETICLE_HOME, pidAlive = isAlive) {
     }
     return reclaimed;
 }
+export function defaultSpawnDaemonDeps() {
+    return {
+        home: RETICLE_HOME,
+        openFile: openSync,
+        closeFile: closeSync,
+        spawnChild: (command, args, options) => spawn(command, [...args], { detached: options.detached, stdio: [...options.stdio] }),
+        pidAlive: isAlive,
+    };
+}
 /**
  * Spawn the reticle daemon as a detached background process, redirecting output to the log file.
  * Writes the PID file from the parent before returning so callers can call isRunning
  * immediately without a race window.
+ *
+ * `deps` is injectable for testing (default: real fs/spawn against ~/.reticle). The same seam
+ * pattern as reclaimStaleDaemons(home, pidAlive).
  */
-export function spawnDaemon(nodeExec, scriptPath, args, port) {
-    mkdirSync(RETICLE_HOME, { recursive: true });
-    const path = pidPath(port);
+export function spawnDaemon(nodeExec, scriptPath, args, port, deps = defaultSpawnDaemonDeps()) {
+    mkdirSync(deps.home, { recursive: true });
+    const pidFilePath = join(deps.home, `daemon-${port}.pid`);
+    const logFilePath = join(deps.home, `daemon-${port}.log`);
     // O_EXCL spawn-lock: only the FIRST racer to create the pidfile spawns. A concurrent second gets
     // EEXIST — if a LIVE daemon owns the port it skips (no duplicate detached daemon, no clobbered pid);
     // a stale pidfile from a crashed daemon is reclaimed. Returns false when it did not spawn.
     let lockFd;
     try {
-        lockFd = openSync(path, 'wx');
+        lockFd = deps.openFile(pidFilePath, 'wx');
     }
     catch {
-        const existing = readPid(port);
-        if (existing !== null && isAlive(existing))
+        const existing = readPid(port, deps.home);
+        if (existing !== null && deps.pidAlive(existing))
             return false;
         try {
-            unlinkSync(path);
-            lockFd = openSync(path, 'wx');
+            unlinkSync(pidFilePath);
+            lockFd = deps.openFile(pidFilePath, 'wx');
         }
         catch {
             return false; // lost a concurrent reclaim race
         }
     }
-    const logFd = openSync(logPath(port), 'a');
-    const child = spawn(nodeExec, [scriptPath, ...args], {
-        detached: true,
-        stdio: ['ignore', logFd, logFd],
-    });
-    if (child.pid !== undefined) {
-        writeFileSync(lockFd, String(child.pid), 'utf8');
+    let logFd;
+    try {
+        logFd = deps.openFile(logFilePath, 'a');
+    }
+    catch {
+        // Log path unwritable (permissions, disk full). Clean up the lock so we don't leave a ghost.
+        deps.closeFile(lockFd);
+        try {
+            unlinkSync(pidFilePath);
+        }
+        catch {
+            // racing another reclaimer — fine
+        }
+        return false;
+    }
+    let child;
+    try {
+        child = deps.spawnChild(nodeExec, [scriptPath, ...args], {
+            detached: true,
+            stdio: ['ignore', logFd, logFd],
+        });
+    }
+    catch {
+        // spawn can throw synchronously on some platforms (e.g. ENOMEM, invalid args).
+        deps.closeFile(logFd);
+        deps.closeFile(lockFd);
+        try {
+            unlinkSync(pidFilePath);
+        }
+        catch {
+            // racing another reclaimer — fine
+        }
+        return false;
+    }
+    // The parent's copy of logFd is no longer needed — spawn duplicated it into the child.
+    deps.closeFile(logFd);
+    // Suppress the async ENOENT/EACCES that fires when the executable is missing or unexecutable.
+    // The failure is already detected synchronously via `child.pid === undefined`; without this
+    // handler the error propagates as an uncaught exception and crashes the parent process.
+    child.on('error', () => undefined);
+    if (child.pid === undefined) {
+        // Spawn failed silently (resource exhaustion, invalid executable on some platforms). The pidfile
+        // is empty — clean it up so discovery doesn't see a ghost, and report failure honestly.
+        deps.closeFile(lockFd);
+        try {
+            unlinkSync(pidFilePath);
+        }
+        catch {
+            // racing another reclaimer — fine
+        }
+        return false;
     }
-    closeSync(lockFd);
+    writeFileSync(lockFd, String(child.pid), 'utf8');
+    deps.closeFile(lockFd);
     child.unref();
     return true;
 }
-//# sourceMappingURL=daemon.js.map

package/dist/domain/domain-model.d.ts

@@ -61,4 +61,3 @@ export interface DomainModel {
     summary: string;
 }
 export declare function buildDomainModel(flows: readonly FlowFile[], contract: CapabilitiesContract | null, runs?: readonly RunRecord[]): DomainModel;
-//# sourceMappingURL=domain-model.d.ts.map

package/dist/domain/domain-model.js

@@ -108,7 +108,7 @@ export function buildDomainModel(flows, contract, runs = []) {
 }
 function buildSummary(flowCount, coverage, gaps, topRisk) {
     if (flowCount === 0) {
-        return 'No saved flows yet — record the critical journeys (reticle_record_start) so the agent learns the app.';
+        return 'No saved flows yet — record the critical journeys (reticle_record{action:"start"}) so the agent learns the app.';
     }
     const parts = [
         `${String(flowCount)} flow${flowCount === 1 ? '' : 's'}: ${String(coverage.asserted)} asserted, ${String(coverage.presenceOnly)} presence-only, ${String(coverage.assertionFree)} assertion-free`,
@@ -124,4 +124,3 @@ function buildSummary(flowCount, coverage, gaps, topRisk) {
     }
     return parts.join('. ') + '.';
 }
-//# sourceMappingURL=domain-model.js.map

package/dist/domain/domain-tools.d.ts

@@ -1,9 +1,2 @@
 import type { ToolDef } from '../tools/tools.js';
-/**
- * reticle_domain — the "learn the app before testing it" tool. Synthesizes every saved flow + the
- * registered capabilities into a compact domain model: the journeys, what each asserts, and the
- * GAPS (declared signals/testids no flow verifies). An agent reads this once instead of crawling
- * the whole app or reading all the source — and it points straight at untested intent.
- */
 export declare const DOMAIN_TOOLS: ToolDef[];
-//# sourceMappingURL=domain-tools.d.ts.map

package/dist/domain/domain-tools.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { asNumber } 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';
@@ -10,11 +11,18 @@ import { instrumentationGapsForFlows } from '../oracles/flow-instrument-gaps.js'
  * GAPS (declared signals/testids no flow verifies). An agent reads this once instead of crawling
  * the whole app or reading all the source — and it points straight at untested intent.
  */
+/** Flows detailed when the caller does not ask for a specific count. */
+const DEFAULT_FLOW_DETAIL_LIMIT = 25;
 export const DOMAIN_TOOLS = [
     {
         name: ReticleTool.DOMAIN,
         description: 'Read the app domain model BEFORE testing: every saved flow with its assertion grade, the consequence that MUST hold for it (mustHold = what it actually tests), the anchors/signals it exercises, plus GAPS — declared signals/testids that NO flow asserts (untested intent), and flows that assert no observable consequence. Use this to decide what to test and where the real risk is, instead of crawling the whole app. Reads .reticle/flows/ + .reticle/contract.json (no browser needed).',
-        inputSchema: {},
+        inputSchema: {
+            limit: z
+                .number()
+                .optional()
+                .describe('Most-recent N flows to detail. Defaults to 25 — the per-flow list grows with every saved flow (measured at ~11KB / ~2,700 tokens at 22 flows) and a large project would spend most of an agent context on flows it is not asking about. `flowCount` is always the true total, and the gaps/coverage summary is computed over ALL flows regardless, so capping the detail never changes the analysis.'),
+        },
         outputSchema: {
             flowCount: z.number(),
             flows: z.array(z.object({
@@ -35,6 +43,10 @@ export const DOMAIN_TOOLS = [
                 signals: z.array(z.string()),
                 stores: z.array(z.string()),
             }),
+            flowsTruncated: z
+                .number()
+                .optional()
+                .describe('How many flows were omitted from `flows` by `limit`. Absent means the listing is complete. gaps/coverage always cover every flow.'),
             coverage: z.object({
                 asserted: z.number(),
                 presenceOnly: z.number(),
@@ -54,7 +66,7 @@ export const DOMAIN_TOOLS = [
                 .optional()
                 .describe('Ready-to-apply instrumentation proposals for gaps that have a source location — { file, line, insert, rationale }. Apply, re-verify, and the app’s observability compounds.'),
         },
-        handler: async (deps) => {
+        handler: async (deps, args) => {
             const names = await deps.flows.list();
             const flows = [];
             for (const name of names) {
@@ -69,8 +81,13 @@ export const DOMAIN_TOOLS = [
             // Self-instrumentation: turn located gaps (unasserted flows with a source stamp) into apply-ready diffs.
             const stepsByName = new Map(flows.map((f) => [f.name, f.steps]));
             const instrumentation = proposeInstrumentation(instrumentationGapsForFlows(model.gaps.unassertedFlows, stepsByName));
-            return instrumentation.length > 0 ? { ...model, instrumentation } : model;
+            // The per-flow detail is capped; `flowCount`, `gaps` and `coverage` are computed over every
+            // flow, so the ANALYSIS is never truncated — only the listing an agent reads past is.
+            const cap = asNumber(args['limit']) ?? DEFAULT_FLOW_DETAIL_LIMIT;
+            const capped = model.flows.length > cap
+                ? { ...model, flows: model.flows.slice(-cap), flowsTruncated: model.flows.length - cap }
+                : model;
+            return instrumentation.length > 0 ? { ...capped, instrumentation } : capped;
         },
     },
 ];
-//# sourceMappingURL=domain-tools.js.map

package/dist/domain/flow-risk.d.ts

@@ -31,4 +31,3 @@ export declare function rankByRisk(entries: {
     name: string;
     risk: FlowRisk;
 }[]): string[];
-//# sourceMappingURL=flow-risk.d.ts.map

package/dist/domain/flow-risk.js

@@ -78,4 +78,3 @@ export function rankByRisk(entries) {
         .sort((a, b) => RANK[b.risk.level] - RANK[a.risk.level] || a.name.localeCompare(b.name))
         .map((e) => e.name);
 }
-//# sourceMappingURL=flow-risk.js.map

package/dist/ee/audit-log.d.ts

@@ -12,4 +12,3 @@ interface AuditEvent {
 /** Record an audit event — gated. Throws EnterpriseLicenseError in production without a valid license. */
 export declare function recordAuditEvent(event: AuditEvent, ctx: GateContext): AuditEvent;
 export {};
-//# sourceMappingURL=audit-log.d.ts.map

package/dist/ee/audit-log.js

@@ -9,4 +9,3 @@ export function recordAuditEvent(event, ctx) {
     assertEnterprise('audit-log', ctx);
     return event; // stub: a real implementation persists to the enterprise audit store
 }
-//# sourceMappingURL=audit-log.js.map

package/dist/events/body-failures.d.ts

@@ -0,0 +1,4 @@
+import { type ReticleEvent } from '@reticlehq/core';
+import type { Contradiction } from './contradictions.js';
+/** Contradictions for 2xx responses whose bodies report failure. One per offending call. */
+export declare function findBodyFailures(events: readonly ReticleEvent[]): Contradiction[];

package/dist/events/body-failures.js

@@ -0,0 +1,113 @@
+import { ContradictionKind, EventType } from '@reticlehq/core';
+/**
+ * A request that returned 2xx and reported failure INSIDE its body.
+ *
+ * The status line is not the outcome. Three shapes make this routine rather than exotic:
+ *
+ *  - **GraphQL** answers HTTP 200 for every error it has ever produced. `errors: [...]` in a 200 body
+ *    is the normal way a GraphQL request fails, so any verdict that reads only the status is blind to
+ *    the entire error surface of an entire ecosystem.
+ *  - **Bulk endpoints** answer 200 for the batch and put per-item results in the body. Measured on a
+ *    shipments console: `POST /api/bulk-hold` → 200, banner reads "9 shipments held", and three of
+ *    the nine carry `{"ok": false, "error": "carrier_locked"}`. Reticle had that body in hand and
+ *    reported `verified: "yes"`.
+ *  - **Envelope APIs** answer 200 with `{"success": false}` — common wherever a gateway normalises
+ *    status codes.
+ *
+ * Every channel above the body agrees with the lie: the request succeeded, the UI advanced, the page
+ * settled, nothing 5xx'd. Only the payload disagrees, which is why this needs body capture — and why
+ * an agent reading a status column can never catch it.
+ */
+/** Keys whose truthiness means "this failed". Checked at the top level and per item. */
+const FAILURE_FLAGS = ['ok', 'success', 'succeeded'];
+/** Keys that, when carrying content, name a failure. */
+const ERROR_KEYS = ['error', 'errors', 'errorMessage', 'failureReason'];
+/** Arrays worth walking for per-item outcomes. Bulk APIs converge on a handful of names. */
+const ITEM_KEYS = ['results', 'items', 'data', 'records', 'responses'];
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Whether one object reports a failure of its own. */
+function reportsFailure(item) {
+    if (!isRecord(item))
+        return false;
+    for (const flag of FAILURE_FLAGS) {
+        if (item[flag] === false)
+            return true;
+    }
+    for (const key of ERROR_KEYS) {
+        const value = item[key];
+        if (value === undefined || value === null)
+            continue;
+        if (Array.isArray(value)) {
+            if (value.length > 0)
+                return true;
+            continue;
+        }
+        // An empty string or an explicit null is an API saying "no error", not an error.
+        if (typeof value === 'string' && value.length === 0)
+            continue;
+        return true;
+    }
+    return false;
+}
+/** Failed / total across the first item array found. Zero total when the body is not a batch. */
+function itemOutcomes(body) {
+    for (const key of ITEM_KEYS) {
+        const list = body[key];
+        if (!Array.isArray(list) || list.length === 0)
+            continue;
+        const failed = list.filter(reportsFailure).length;
+        return { failed, total: list.length };
+    }
+    return { failed: 0, total: 0 };
+}
+function parse(raw) {
+    if (typeof raw !== 'string' || raw.length === 0)
+        return undefined;
+    try {
+        const parsed = JSON.parse(raw);
+        return isRecord(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined; // not JSON — nothing to read, and guessing at prose would invent findings
+    }
+}
+const OK_MIN = 200;
+const OK_MAX = 300;
+/** Contradictions for 2xx responses whose bodies report failure. One per offending call. */
+export function findBodyFailures(events) {
+    const found = [];
+    for (const event of events) {
+        if (event.type !== EventType.NET_REQUEST)
+            continue;
+        const status = event.data['status'];
+        if (typeof status !== 'number' || status < OK_MIN || status >= OK_MAX)
+            continue;
+        const body = parse(event.data['responseBody']);
+        if (body === undefined)
+            continue;
+        const url = typeof event.data['url'] === 'string' ? event.data['url'] : '';
+        const method = typeof event.data['method'] === 'string' ? event.data['method'] : '';
+        const where = `${method} ${url} → ${String(status)}`;
+        const { failed, total } = itemOutcomes(body);
+        if (failed > 0) {
+            found.push({
+                kind: ContradictionKind.PARTIAL_FAILURE_IN_OK_RESPONSE,
+                claim: `the request returned ${String(status)} and the page treated it as done`,
+                counter: `its body reports ${String(failed)} of ${String(total)} items FAILED`,
+                detail: `${where} — a batch endpoint's status describes the BATCH, not the items; whatever the UI says it did, ${String(failed)} of them did not happen`,
+            });
+            continue;
+        }
+        if (reportsFailure(body)) {
+            found.push({
+                kind: ContradictionKind.PARTIAL_FAILURE_IN_OK_RESPONSE,
+                claim: `the request returned ${String(status)} and the page treated it as done`,
+                counter: 'its body reports the operation FAILED',
+                detail: `${where} — the status line and the payload disagree; the payload is the outcome (a GraphQL error is always a 200)`,
+            });
+        }
+    }
+    return found;
+}

package/dist/events/contradictions.d.ts

@@ -0,0 +1,53 @@
+import { ContradictionKind, type ReticleEvent } from '@reticlehq/core';
+/**
+ * The contradiction hunter.
+ *
+ * Every other check in Reticle reads ONE channel and asks "did something bad happen there?" — a
+ * console error, a 500, a control that did nothing. A human can do that too, just slower.
+ *
+ * This asks a question a human structurally cannot: do the channels DISAGREE with each other? A
+ * person watching an app has exactly one channel open — the screen. The agent holds the DOM, the
+ * store, the app's own signals, the console and the network in one causally ordered window, so it
+ * can catch the case where the screen says one thing and the network says the opposite.
+ *
+ * That gap is where false greens live. The archetype ships in both desktop demos: click Archive, the
+ * row disappears, the status line reads "archived", and the IPC call rejected into a swallowed
+ * `.catch()`. A screenshot agrees. A DOM assertion agrees. A human agrees. Only the disagreement
+ * between channels reveals it.
+ *
+ * Pure: a window of events in, findings out. No session, no IO, no clock.
+ */
+export interface Contradiction {
+    kind: ContradictionKind;
+    /** What one channel asserted — the optimistic half. */
+    claim: string;
+    /** What the other channel asserted — the half that contradicts it. */
+    counter: string;
+    /** Concrete evidence, so the agent can go straight to the call or the control. */
+    detail: string;
+}
+export interface ContradictionOptions {
+    /** The action that opened this window, when one did. Enables the no-effect check. */
+    action?: string | undefined;
+    /**
+     * Events from BEFORE the window, used only to LEARN — never reported on. Some disagreements are
+     * with something the API stated earlier in the session, which an action-scoped window cannot
+     * contain. See `findUnitMismatches` for the measured case this exists for.
+     */
+    prior?: readonly ReticleEvent[] | undefined;
+    /**
+     * DOM mutations observed INSIDE the target's own subtree, as the act tool measured them.
+     *
+     * The no-effect check used to require a completely empty window, which is a statement about the
+     * PAGE rather than about the action — and no real app has a quiet page. Measured on a shipments
+     * console with a background event stream: clicking an inert heading produced `domMutatedWithin: 0`
+     * and four ambient events (a scroll position, an unrelated store update, a perf sample), so the
+     * window was not empty and the dead control went unreported. The user's framing of this is exact:
+     * the DOM moving after an action is not evidence that the action moved it.
+     *
+     * Undefined means the caller did not measure it — the check then falls back to the empty-window
+     * test, which is weaker but never wrong in the direction of a false accusation.
+     */
+    mutatedWithin?: number | undefined;
+}
+export declare function findContradictions(events: readonly ReticleEvent[], options?: ContradictionOptions): Contradiction[];