@reticlehq/server 2.4.0 → 2.5.0

package/dist/{daemon.js → daemon/daemon.js}

@@ -1,19 +1,61 @@
 import { join } from 'node:path';
 import { homedir } from 'node:os';
-import { mkdirSync, readFileSync, writeFileSync, existsSync, unlinkSync, openSync, closeSync, readdirSync, } from 'node:fs';
+import { mkdirSync, readFileSync, writeFileSync, existsSync, unlinkSync, openSync, closeSync, readdirSync, statSync, renameSync, } from 'node:fs';
 import { spawn } from 'node:child_process';
-import { daemonRegistryFileName, daemonRegistryPort, DaemonRegistryEntrySchema, pickDaemonPort, } from '@reticlehq/core';
-const RETICLE_HOME = join(homedir(), '.reticle');
-function pidPath(port, home = RETICLE_HOME) {
+import { daemonRegistryFileName, ReticleEnv } from '@reticlehq/core';
+import { log } from '../log.js';
+/** Env override for the whole state directory — see ReticleEnv.STATE_DIR. */
+export const STATE_DIR_ENV = ReticleEnv.STATE_DIR;
+/**
+ * Where the daemon keeps pidfiles, the discovery registry and its logs.
+ *
+ * `~/.reticle` unless overridden. The override exists because a read-only $HOME is not hypothetical
+ * — a sandboxed agent or a locked-down Windows profile cannot write there, and until now that meant
+ * the daemon could not start at all. Read per call rather than captured at import, so a test (and a
+ * wrapper that sets it late) sees the current value.
+ */
+export function reticleStateHome() {
+    const override = process.env[STATE_DIR_ENV];
+    if (override !== undefined && override.length > 0)
+        return override;
+    return join(homedir(), '.reticle');
+}
+function pidPath(port, home = reticleStateHome()) {
     return join(home, `daemon-${port}.pid`);
 }
 function registryPath(port) {
-    return join(RETICLE_HOME, daemonRegistryFileName(port));
+    return join(reticleStateHome(), daemonRegistryFileName(port));
 }
 export function logPath(port) {
-    return join(RETICLE_HOME, `daemon-${port}.log`);
+    return join(reticleStateHome(), `daemon-${port}.log`);
 }
-export function readPid(port, home = RETICLE_HOME) {
+/**
+ * How large a daemon log may get before it is rolled over to `<name>.1`.
+ *
+ * It was unbounded. A real dev machine reached **24MB** on one port, which is not merely untidy: it
+ * is the difference between a log somebody opens and a log somebody gives up on, and it is disk that
+ * nothing ever reclaims. One previous generation is kept, because the question people bring to this
+ * file ("what happened just now?") is answered by the current one and the question they bring next
+ * ("and just before that?") is answered by the other.
+ */
+export const MAX_DAEMON_LOG_BYTES = 8 * 1024 * 1024;
+/**
+ * Roll the log over if it has grown past the cap. Best-effort: a daemon must still start when the
+ * log cannot be rotated, because failing to launch over housekeeping is strictly worse than a large
+ * file.
+ */
+export function rotateDaemonLog(path, deps, max = MAX_DAEMON_LOG_BYTES) {
+    try {
+        if (max >= deps.fileSize(path))
+            return false;
+        deps.renameFile(path, `${path}.1`);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function readPid(port, home = reticleStateHome()) {
     const path = pidPath(port, home);
     if (!existsSync(path))
         return null;
@@ -30,7 +72,7 @@ export function isAlive(pid) {
     }
 }
 export function writePid(port) {
-    mkdirSync(RETICLE_HOME, { recursive: true });
+    mkdirSync(reticleStateHome(), { recursive: true });
     writeFileSync(pidPath(port), String(process.pid), 'utf8');
 }
 /**
@@ -39,7 +81,7 @@ export function writePid(port) {
  * the orphan-race guard: a losing childB (EADDRINUSE) must not delete the winning childA's live pidfile.
  */
 export function shouldRemovePid(owner, expectedPid, alive) {
-    return owner === null || owner === expectedPid || !alive;
+    return null === owner || owner === expectedPid || !alive;
 }
 export function removePid(port, expectedPid = process.pid) {
     const path = pidPath(port);
@@ -66,14 +108,14 @@ export function writeDaemonRegistry(port, meta) {
         ...(meta.projectId !== undefined ? { projectId: meta.projectId } : {}),
     };
     try {
-        mkdirSync(RETICLE_HOME, { recursive: true });
+        mkdirSync(reticleStateHome(), { recursive: true });
         writeFileSync(registryPath(port), JSON.stringify(entry), 'utf8');
     }
     catch {
         // discovery is a convenience — never block startup on it
     }
 }
-export function removeDaemonRegistry(port) {
+function removeDaemonRegistry(port) {
     const path = registryPath(port);
     try {
         if (existsSync(path))
@@ -83,34 +125,6 @@ export function removeDaemonRegistry(port) {
         // racing another cleaner — already gone
     }
 }
-/**
- * Discover the port of a live daemon serving `projectId` by reading the registry entries in ~/.reticle.
- * Returns null when none matches (caller falls back to the default port — never guesses a mismatched
- * daemon). Stale entries (crashed daemons) are ignored via the pid liveness probe.
- */
-export function discoverDaemonPortForProject(projectId) {
-    const entries = [];
-    let files;
-    try {
-        files = readdirSync(RETICLE_HOME);
-    }
-    catch {
-        return null; // no ~/.reticle yet
-    }
-    for (const file of files) {
-        if (daemonRegistryPort(file) === null)
-            continue;
-        try {
-            const parsed = DaemonRegistryEntrySchema.safeParse(JSON.parse(readFileSync(join(RETICLE_HOME, file), 'utf8')));
-            if (parsed.success)
-                entries.push(parsed.data);
-        }
-        catch {
-            // unreadable/corrupt entry — skip it
-        }
-    }
-    return pickDaemonPort(entries, projectId, isAlive);
-}
 export function isRunning(port) {
     const pid = readPid(port);
     return pid !== null && isAlive(pid);
@@ -124,12 +138,12 @@ export function discoverDaemonPort() {
     reclaimStaleDaemons(); // sweep crashed daemons' stale pidfiles before scanning for live ones
     let found = null;
     try {
-        for (const file of readdirSync(RETICLE_HOME)) {
+        for (const file of readdirSync(reticleStateHome())) {
             const m = /^daemon-(\d+)\.pid$/.exec(file);
-            if (m === null)
+            if (null === m)
                 continue;
             const port = Number(m[1]);
-            if (isRunning(port) && (found === null || port < found))
+            if (isRunning(port) && (null === found || port < found))
                 found = port;
         }
     }
@@ -144,7 +158,7 @@ export function discoverDaemonPort() {
  * Returns the ports reclaimed. `home` and `pidAlive` are injectable for testing (default to the real
  * ~/.reticle and the process.kill(pid,0) liveness probe).
  */
-export function reclaimStaleDaemons(home = RETICLE_HOME, pidAlive = isAlive) {
+export function reclaimStaleDaemons(home = reticleStateHome(), pidAlive = isAlive) {
     const reclaimed = [];
     let files;
     try {
@@ -155,7 +169,7 @@ export function reclaimStaleDaemons(home = RETICLE_HOME, pidAlive = isAlive) {
     }
     for (const file of files) {
         const match = /^daemon-(\d+)\.pid$/.exec(file);
-        if (match === null)
+        if (null === match)
             continue;
         const path = join(home, file);
         let pid = null;
@@ -167,7 +181,7 @@ export function reclaimStaleDaemons(home = RETICLE_HOME, pidAlive = isAlive) {
         catch {
             pid = null; // unreadable pidfile counts as stale
         }
-        if (pid === null || !pidAlive(pid)) {
+        if (null === pid || !pidAlive(pid)) {
             try {
                 unlinkSync(path);
                 removeDaemonRegistry(Number(match[1])); // drop the sidecar discovery entry too
@@ -180,11 +194,13 @@ export function reclaimStaleDaemons(home = RETICLE_HOME, pidAlive = isAlive) {
     }
     return reclaimed;
 }
-export function defaultSpawnDaemonDeps() {
+function defaultSpawnDaemonDeps() {
     return {
-        home: RETICLE_HOME,
+        home: reticleStateHome(),
         openFile: openSync,
         closeFile: closeSync,
+        fileSize: (path) => (existsSync(path) ? statSync(path).size : 0),
+        renameFile: renameSync,
         spawnChild: (command, args, options) => spawn(command, [...args], { detached: options.detached, stdio: [...options.stdio] }),
         pidAlive: isAlive,
     };
@@ -198,7 +214,20 @@ export function defaultSpawnDaemonDeps() {
  * pattern as reclaimStaleDaemons(home, pidAlive).
  */
 export function spawnDaemon(nodeExec, scriptPath, args, port, deps = defaultSpawnDaemonDeps()) {
-    mkdirSync(deps.home, { recursive: true });
+    try {
+        mkdirSync(deps.home, { recursive: true });
+    }
+    catch (err) {
+        // The log-file open below has always been guarded; this was not, so the ONE failure a sandboxed
+        // agent actually hits — a read-only $HOME — escaped as a raw EACCES naming nothing. Refuse
+        // loudly, and name the way out.
+        log('reticle_daemon_state_unwritable', {
+            home: deps.home,
+            error: err instanceof Error ? err.message : String(err),
+            fix: `Reticle could not create its state directory. Set ${STATE_DIR_ENV} to a writable path and retry.`,
+        });
+        return false;
+    }
     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
@@ -220,6 +249,9 @@ export function spawnDaemon(nodeExec, scriptPath, args, port, deps = defaultSpaw
             return false; // lost a concurrent reclaim race
         }
     }
+    // Roll the log BEFORE opening the append handle, or the daemon writes into the renamed file
+    // through an fd that no longer matches any name anyone can find.
+    rotateDaemonLog(logFilePath, deps);
     let logFd;
     try {
         logFd = deps.openFile(logFilePath, 'a');

package/dist/daemon/idle-grace.d.ts

@@ -0,0 +1,32 @@
+/**
+ * How long an idle daemon is given before it shuts itself down.
+ *
+ * It used to be one number for every case, and at 5 minutes that number killed live runs: 187
+ * `reticle_daemon_idle_shutdown` lines on one user's machine, with their editor's Reticle
+ * disconnecting each time; and in the fixtures gate it fired during long dependency installs, so apps
+ * that booted afterwards hit ERR_CONNECTION_REFUSED and were scored as install failures when nothing
+ * was wrong with their install.
+ *
+ * Reverting is not an option. Daemons used to sit idle a median of 28 minutes at a 0.04% duty cycle
+ * because "an agent is attached" alone kept one alive for a whole editor session, and the widened
+ * rule is what fixed that.
+ *
+ * The distinction is TIME, not state. Mid-install an attached daemon is state-identical to one in an
+ * empty directory — nothing has been asked of either. What differs is how long it is reasonable to
+ * wait: quiet with a client attached means the human is thinking or the install is slow; the same
+ * quiet with nobody attached means the daemon is unwanted. Both still exit.
+ */
+/**
+ * An attached daemon waits this many times the base grace. Six is chosen against the two measurements
+ * that matter: the default base is 5 minutes, so an attached daemon survives 30 — comfortably past
+ * the slow installs that were killing runs, and comfortably short of the 28-minute median idle the
+ * shorter rule was introduced to end.
+ */
+export declare const ATTACHED_GRACE_MULTIPLIER = 6;
+/**
+ * @param overrideMs an explicit attached grace (RETICLE_IDLE_ATTACHED_MS). Derived from the base when
+ * absent — but the derived value is arithmetic on a number the caller also controls, and a test that
+ * has to reason about both is a test that breaks for the wrong reason. Configuring it directly is
+ * what lets the e2e spec assert the BEHAVIOUR (an attached daemon exits) without racing a product.
+ */
+export declare function idleGraceMs(baseMs: number, agentAttached: boolean, overrideMs?: number): number;

package/dist/daemon/idle-grace.js

@@ -0,0 +1,41 @@
+/**
+ * How long an idle daemon is given before it shuts itself down.
+ *
+ * It used to be one number for every case, and at 5 minutes that number killed live runs: 187
+ * `reticle_daemon_idle_shutdown` lines on one user's machine, with their editor's Reticle
+ * disconnecting each time; and in the fixtures gate it fired during long dependency installs, so apps
+ * that booted afterwards hit ERR_CONNECTION_REFUSED and were scored as install failures when nothing
+ * was wrong with their install.
+ *
+ * Reverting is not an option. Daemons used to sit idle a median of 28 minutes at a 0.04% duty cycle
+ * because "an agent is attached" alone kept one alive for a whole editor session, and the widened
+ * rule is what fixed that.
+ *
+ * The distinction is TIME, not state. Mid-install an attached daemon is state-identical to one in an
+ * empty directory — nothing has been asked of either. What differs is how long it is reasonable to
+ * wait: quiet with a client attached means the human is thinking or the install is slow; the same
+ * quiet with nobody attached means the daemon is unwanted. Both still exit.
+ */
+/**
+ * An attached daemon waits this many times the base grace. Six is chosen against the two measurements
+ * that matter: the default base is 5 minutes, so an attached daemon survives 30 — comfortably past
+ * the slow installs that were killing runs, and comfortably short of the 28-minute median idle the
+ * shorter rule was introduced to end.
+ */
+export const ATTACHED_GRACE_MULTIPLIER = 6;
+/**
+ * @param overrideMs an explicit attached grace (RETICLE_IDLE_ATTACHED_MS). Derived from the base when
+ * absent — but the derived value is arithmetic on a number the caller also controls, and a test that
+ * has to reason about both is a test that breaks for the wrong reason. Configuring it directly is
+ * what lets the e2e spec assert the BEHAVIOUR (an attached daemon exits) without racing a product.
+ */
+export function idleGraceMs(baseMs, agentAttached, overrideMs) {
+    // A non-positive base means the watcher is disabled; multiplying must not resurrect it.
+    if (baseMs <= 0)
+        return baseMs;
+    if (!agentAttached)
+        return baseMs;
+    return overrideMs !== undefined && overrideMs > 0
+        ? overrideMs
+        : baseMs * ATTACHED_GRACE_MULTIPLIER;
+}

package/dist/{idle-shutdown.d.ts → daemon/idle-shutdown.d.ts}

@@ -5,6 +5,14 @@ export interface IdleShutdownOptions {
     onShutdown: () => void;
     /** Continuous-idle window before shutdown. `0` (or negative) disables the watcher entirely. */
     graceMs: number;
+    /**
+     * Is an agent's MCP client attached right now? An attached daemon gets a much longer grace — quiet
+     * with a client present means a slow install or a thinking human, not an unwanted daemon. It still
+     * exits. See idle-grace.
+     */
+    agentAttached?: () => boolean;
+    /** Explicit attached grace (RETICLE_IDLE_ATTACHED_MS); derived from graceMs when absent. */
+    attachedGraceMs?: number;
     /** How often to re-check idleness. */
     checkIntervalMs?: number;
     /** Injected clock — never read wall-clock time in logic (repo rule). */
@@ -30,4 +38,9 @@ export declare class IdleShutdown {
  * Resolve the idle-shutdown grace from `RETICLE_IDLE_SHUTDOWN_MS`: a non-negative integer of milliseconds,
  * `0` to disable. Anything missing/invalid falls back to the default. Pure.
  */
+/**
+ * The idle re-check cadence, from the environment. Same shape as the grace resolver: a bad value
+ * falls back rather than throwing, and 0/negative is not a legal cadence (it would spin).
+ */
+export declare function resolveIdleCheckMs(raw: string | undefined): number;
 export declare function resolveIdleShutdownMs(raw: string | undefined): number;

package/dist/{idle-shutdown.js → daemon/idle-shutdown.js}

@@ -1,5 +1,6 @@
 import { SESSION_LIFECYCLE } from '@reticlehq/core';
-import { log } from './log.js';
+import { idleGraceMs } from './idle-grace.js';
+import { log } from '../log.js';
 /**
  * Self-terminates an idle daemon so Reticle never lingers eating a user's resources (the daemon process,
  * any headless Chromium the pool launched, and the bound port) after the editor closes. The `reticle mcp`
@@ -15,12 +16,16 @@ export class IdleShutdown {
     #isIdle;
     #onShutdown;
     #graceMs;
+    #agentAttached;
+    #attachedGraceMs;
     #checkMs;
     #clock;
     constructor(opts) {
         this.#isIdle = opts.isIdle;
         this.#onShutdown = opts.onShutdown;
         this.#graceMs = opts.graceMs;
+        this.#agentAttached = opts.agentAttached;
+        this.#attachedGraceMs = opts.attachedGraceMs;
         this.#checkMs = opts.checkIntervalMs ?? SESSION_LIFECYCLE.DAEMON_IDLE_CHECK_MS;
         this.#clock = opts.clock ?? (() => Date.now());
     }
@@ -34,9 +39,15 @@ export class IdleShutdown {
         }
         const now = this.#clock();
         this.#idleSince ??= now;
-        if (now - this.#idleSince >= this.#graceMs) {
+        // Read per CHECK, not at construction: a client attaches and detaches during a daemon's life, and
+        // the question "how long should this quiet be tolerated" is only answerable now. See idle-grace.
+        const grace = idleGraceMs(this.#graceMs, this.#agentAttached?.() ?? false, this.#attachedGraceMs);
+        if (now - this.#idleSince >= grace) {
             this.#fired = true;
-            log('reticle_daemon_idle_shutdown', { idleMs: now - this.#idleSince });
+            log('reticle_daemon_idle_shutdown', {
+                idleMs: now - this.#idleSince,
+                attached: this.#agentAttached?.() ?? false,
+            });
             this.#onShutdown();
         }
     }
@@ -57,8 +68,20 @@ export class IdleShutdown {
  * Resolve the idle-shutdown grace from `RETICLE_IDLE_SHUTDOWN_MS`: a non-negative integer of milliseconds,
  * `0` to disable. Anything missing/invalid falls back to the default. Pure.
  */
+/**
+ * The idle re-check cadence, from the environment. Same shape as the grace resolver: a bad value
+ * falls back rather than throwing, and 0/negative is not a legal cadence (it would spin).
+ */
+export function resolveIdleCheckMs(raw) {
+    if (raw === undefined || '' === raw.trim())
+        return SESSION_LIFECYCLE.DAEMON_IDLE_CHECK_MS;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n <= 0)
+        return SESSION_LIFECYCLE.DAEMON_IDLE_CHECK_MS;
+    return Math.floor(n);
+}
 export function resolveIdleShutdownMs(raw) {
-    if (raw === undefined || raw.trim() === '')
+    if (raw === undefined || '' === raw.trim())
         return SESSION_LIFECYCLE.DAEMON_IDLE_SHUTDOWN_MS;
     const n = Number(raw);
     if (!Number.isFinite(n) || n < 0)

package/dist/domain/domain-model.js

@@ -107,11 +107,11 @@ export function buildDomainModel(flows, contract, runs = []) {
     };
 }
 function buildSummary(flowCount, coverage, gaps, topRisk) {
-    if (flowCount === 0) {
+    if (0 === flowCount) {
         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`,
+        `${String(flowCount)} flow${1 === flowCount ? '' : 's'}: ${String(coverage.asserted)} asserted, ${String(coverage.presenceOnly)} presence-only, ${String(coverage.assertionFree)} assertion-free`,
     ];
     if (topRisk !== undefined) {
         parts.push(`test first: ${topRisk.name} (${topRisk.reason})`);

package/dist/events/body-failures.js

@@ -25,19 +25,19 @@ 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);
+    return 'object' === typeof value && 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)
+        if (false === item[flag])
             return true;
     }
     for (const key of ERROR_KEYS) {
         const value = item[key];
-        if (value === undefined || value === null)
+        if (value === undefined || null === value)
             continue;
         if (Array.isArray(value)) {
             if (value.length > 0)
@@ -45,7 +45,7 @@ function reportsFailure(item) {
             continue;
         }
         // An empty string or an explicit null is an API saying "no error", not an error.
-        if (typeof value === 'string' && value.length === 0)
+        if ('string' === typeof value && 0 === value.length)
             continue;
         return true;
     }
@@ -55,7 +55,7 @@ function reportsFailure(item) {
 function itemOutcomes(body) {
     for (const key of ITEM_KEYS) {
         const list = body[key];
-        if (!Array.isArray(list) || list.length === 0)
+        if (!Array.isArray(list) || 0 === list.length)
             continue;
         const failed = list.filter(reportsFailure).length;
         return { failed, total: list.length };
@@ -63,7 +63,7 @@ function itemOutcomes(body) {
     return { failed: 0, total: 0 };
 }
 function parse(raw) {
-    if (typeof raw !== 'string' || raw.length === 0)
+    if (typeof raw !== 'string' || 0 === raw.length)
         return undefined;
     try {
         const parsed = JSON.parse(raw);
@@ -87,8 +87,8 @@ export function findBodyFailures(events) {
         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 url = 'string' === typeof event.data['url'] ? event.data['url'] : '';
+        const method = 'string' === typeof event.data['method'] ? event.data['method'] : '';
         const where = `${method} ${url} → ${String(status)}`;
         const { failed, total } = itemOutcomes(body);
         if (failed > 0) {

package/dist/events/contradictions.d.ts

@@ -50,4 +50,4 @@ export interface ContradictionOptions {
      */
     mutatedWithin?: number | undefined;
 }
-export declare function findContradictions(events: readonly ReticleEvent[], options?: ContradictionOptions): Contradiction[];
+export declare function findContradictions(allEvents: readonly ReticleEvent[], options?: ContradictionOptions): Contradiction[];

package/dist/events/contradictions.js

@@ -1,4 +1,4 @@
-import { ContradictionKind, EventType, MUTATING_METHODS } from '@reticlehq/core';
+import { ContradictionKind, EventType, MUTATING_METHODS, isDevToolingUrl, } from '@reticlehq/core';
 import { findStaleResponses } from './stale-response.js';
 import { findBodyFailures } from './body-failures.js';
 import { findEchoMismatches } from './echo-mismatch.js';
@@ -14,7 +14,7 @@ function netCall(e) {
         // Neither present = no verdict was ever reported, which stays undefined all the way through.
         ok: e.data['ok'] === undefined && status === undefined
             ? undefined
-            : e.data['ok'] === true || (e.data['ok'] === undefined && (status ?? 0) < 400),
+            : true === e.data['ok'] || (e.data['ok'] === undefined && (status ?? 0) < 400),
     };
 }
 /**
@@ -95,7 +95,7 @@ function failureAcknowledged(events) {
             return false;
         const path = asString(e.data['path']) ?? '';
         const value = e.data['value'];
-        return ACKNOWLEDGED.test(path) || (typeof value === 'string' && ACKNOWLEDGED.test(value));
+        return ACKNOWLEDGED.test(path) || ('string' === typeof value && ACKNOWLEDGED.test(value));
     });
 }
 function describe(call) {
@@ -125,13 +125,44 @@ const MUST_DO_SOMETHING = new Set(['click', 'dblclick', 'submit']);
  */
 function didNothing(events, requests, mutatedWithin) {
     if (mutatedWithin === undefined)
-        return events.length === 0;
+        return 0 === events.length;
     if (mutatedWithin > 0 || requests.length > 0)
         return false;
     return !events.some((e) => e.type === EventType.ROUTE_CHANGE || e.type === EventType.VISIBLE_SHOWN);
 }
-export function findContradictions(events, options = {}) {
+/** Net-shaped events — the only ones that carry a URL a dev-tooling channel could occupy. */
+const NET_TYPES = new Set([
+    EventType.NET_PENDING,
+    EventType.NET_REQUEST,
+    EventType.NET_STREAM,
+]);
+/**
+ * Split the window into the app's traffic and the dev toolchain's own (see `DevToolingChannel`).
+ *
+ * NOTHING below may judge the toolchain. Reported from a real drive: a correct Next.js navigation
+ * graded `verified: "no"` because the dev overlay was resolving a source map for an unrelated React
+ * key warning, and that in-flight `POST /__nextjs_original-stack-frames` read as "the UI advanced
+ * over a request that never settled". Every app that logs one dev warning got a false negative on
+ * every action. The overlay's own 404s and duplicate fetches are the same story on other checks,
+ * which is why the split happens ONCE here rather than in the one check that reported it.
+ */
+function splitDevTooling(events) {
+    const ignored = [];
+    const app = events.filter((e) => {
+        if (!NET_TYPES.has(e.type))
+            return true;
+        const url = asString(e.data['url']);
+        if (!isDevToolingUrl(url))
+            return true;
+        if (url !== undefined && !ignored.includes(url))
+            ignored.push(url);
+        return false;
+    });
+    return { app, ignored };
+}
+export function findContradictions(allEvents, options = {}) {
     const found = [];
+    const { app: events, ignored: ignoredDevTooling } = splitDevTooling(allEvents);
     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.
@@ -160,7 +191,7 @@ export function findContradictions(events, options = {}) {
             },
         ];
     }
-    const failed = settled.filter((c) => c.ok === false);
+    const failed = settled.filter((c) => false === c.ok);
     const advanced = uiAdvanced(events);
     const signals = events
         .filter((e) => e.type === EventType.SIGNAL)
@@ -170,7 +201,19 @@ export function findContradictions(events, options = {}) {
     // the control worked, the DESTINATION is empty — which is why every "did the click do something"
     // heuristic passes it, a route change being unambiguously something.
     const routed = events.some((e) => e.type === EventType.ROUTE_CHANGE);
-    const rendered = events.some((e) => e.type === EventType.DOM_ADDED || e.type === EventType.DOM_REMOVED);
+    // `dom.text` counts as rendered, and it has to: React reconciles a destination IN PLACE far more
+    // often than it adds nodes. Measured on three ordinary sidebar navigations of the bench app — every
+    // one emitted { dom.attr:2, dom.text:2, render.commit, state.change } and ZERO dom.added/removed,
+    // so all three were flagged as blank destinations, `verified` came back "no" on a correct green,
+    // and a bug_found was emitted for a navigation that worked.
+    //
+    // Deliberately NOT `dom.attr`: the nav link marks itself active whether or not the destination
+    // rendered, which is the true positive this rule exists for. Deliberately NOT `render.commit`
+    // either: React commits a render for a component that returns null, which is one of the very bugs
+    // named in `detail` below.
+    const rendered = events.some((e) => e.type === EventType.DOM_ADDED ||
+        e.type === EventType.DOM_REMOVED ||
+        e.type === EventType.DOM_TEXT);
     const fetched = events.some((e) => e.type === EventType.NET_REQUEST || e.type === EventType.NET_PENDING);
     if (routed && !rendered && !fetched) {
         found.push({
@@ -187,7 +230,7 @@ export function findContradictions(events, options = {}) {
     // Checked BEFORE the success-claim rules, because it is the sharper reading of the same events:
     // the app did not claim success, it claimed the wrong failure. Telling someone their password is
     // wrong while the backend is down sends them to fix something they cannot fix.
-    const serverFaults = settled.filter((c) => c.ok === false && c.status !== undefined && c.status >= SERVER_FAULT_MIN);
+    const serverFaults = settled.filter((c) => false === c.ok && c.status !== undefined && c.status >= SERVER_FAULT_MIN);
     const userBlame = [
         ...signals.filter((name) => BLAMES_USER.test(name)),
         ...events
@@ -228,7 +271,7 @@ export function findContradictions(events, options = {}) {
     // Writes only: a GET that changes nothing is a prefetch; a POST that changes nothing is a lost
     // write, a response parsed into the void, or a render that never happened.
     if (!advanced) {
-        const ignoredWrites = settled.filter((c) => c.ok === true && isMutating(c));
+        const ignoredWrites = settled.filter((c) => true === c.ok && isMutating(c));
         if (ignoredWrites.length > 0) {
             found.push({
                 kind: ContradictionKind.RESPONSE_IGNORED,
@@ -274,7 +317,14 @@ export function findContradictions(events, options = {}) {
                 kind: ContradictionKind.REQUEST_NEVER_SETTLED,
                 claim: 'the UI moved forward and the action reported done',
                 counter: `${String(inFlight.length)} request(s) were still in flight`,
-                detail: inFlight.map((p) => describe(p.call)).join('; '),
+                // The exclusion is never silent: if the toolchain's own traffic was dropped from this count,
+                // the finding says which URLs, so an agent reading it can see what Reticle chose to ignore.
+                detail: [
+                    inFlight.map((p) => describe(p.call)).join('; '),
+                    ...(0 === ignoredDevTooling.length
+                        ? []
+                        : [`ignored as dev tooling: ${ignoredDevTooling.join(', ')}`]),
+                ].join(' — '),
             });
         }
     }