@reticlehq/server 2.7.0 → 2.8.0

package/dist/cli/doctor-sessions-line.js

@@ -0,0 +1,66 @@
+import { SELF_RECOVERING_MARKER } from '../session/no-session-diagnosis.js';
+/**
+ * The line `doctor` was missing: is anything actually CONNECTED?
+ *
+ * `doctor` collapses the first-run failure modes into one command, and it checked every one of them
+ * except the one the funnel actually stalls on. A user who has installed the SDK, wired the plugin
+ * and started the daemon runs `doctor`, gets node, chromium, daemon, bridge port and desktop wiring
+ * all ✓, and is no better off — because the thing that is wrong is that no page has ever dialled in,
+ * and nothing on that screen mentions pages.
+ *
+ * The daemon has always known. `/status` carries `sessionCount`, the session list, and `why` — the
+ * same no-session diagnosis an agent gets from an empty `reticle_sessions`, which is careful about
+ * what it can and cannot prove. `reticle status` prints it. `doctor` fetched the identical payload
+ * to read `version` and `contract` off it and dropped the rest on the floor.
+ *
+ * So this invents no new diagnosis. It surfaces one that already exists, on the command a stuck human
+ * runs, which is the difference between a checklist that ends in "everything is fine" and one that
+ * ends in a next action.
+ *
+ * Pure and payload-shaped rather than reaching for the bridge: `doctor` runs in a separate process
+ * from the daemon and can only ever know what `/status` told it.
+ */
+/**
+ * The diagnosis is written for an AGENT, and `doctor` has a human in front of it.
+ *
+ * Every branch of it ends by telling the reader to call `reticle_sessions` again, which is right for
+ * the caller it was written for and useless to somebody in a shell: an MCP tool is not something you
+ * can type. Printing it unchanged would make `doctor` end on a recovery its reader cannot perform,
+ * which is the same defect as the aged-out lease message that told an agent to ask a human to reopen
+ * a tab that never existed.
+ *
+ * So the last sentence is swapped for the shell equivalent of itself. Only that sentence — the rest
+ * of the diagnosis is about the app and reads the same to either audience.
+ */
+const HUMAN_RETRY = 'Then run `reticle doctor` again — it will appear within a second of the page loading.';
+function forAHuman(why) {
+    // Imported, not re-typed: a copy of a sentence that has to match another file's byte-for-byte is a
+    // drift bug with a delay on it, and the failure is silent — the swap simply stops happening and
+    // doctor goes back to telling a human to call an MCP tool.
+    return why.replace(SELF_RECOVERING_MARKER, HUMAN_RETRY);
+}
+function countOf(facts) {
+    const raw = facts.sessionCount;
+    return 'number' === typeof raw && Number.isFinite(raw) && raw >= 0 ? raw : undefined;
+}
+export function sessionsLine(facts) {
+    const count = countOf(facts);
+    if (count === undefined) {
+        // An older daemon that does not report it. Saying "0 connected" here would be a claim about the
+        // app made from a payload that never mentioned the app — the exact kind of confident wrong
+        // sentence the no-session diagnosis exists to avoid.
+        return { text: '  sessions     ? this daemon did not report connected pages (older build)' };
+    }
+    if (count > 0) {
+        const plural = 1 === count ? 'page' : 'pages';
+        return { text: `  sessions     ✓ ${String(count)} ${plural} connected` };
+    }
+    const why = 'string' === typeof facts.why && facts.why.length > 0 ? forAHuman(facts.why) : undefined;
+    return {
+        // Deliberately ✗ rather than a neutral note. Zero connected pages is why somebody is running
+        // doctor, and a ✓-coloured checklist that hides the one failing thing is how the old output
+        // convinced people their setup was fine.
+        text: '  sessions     ✗ no page has connected to this daemon',
+        ...(why === undefined ? {} : { why }),
+    };
+}

package/dist/cli/port-holder.d.ts

@@ -17,6 +17,16 @@ export interface PortHolder {
     pid: number;
     command: string;
 }
+/**
+ * Run a lookup and return its stdout, or null if it could not run.
+ *
+ * Null on ANY failure — no lsof (every Windows user, a slim container), a non-zero exit, a throw.
+ * This is a diagnostic nicety inside the commands people run when things are already broken; it must
+ * never be the reason one of them fails. Every caller handles the null by saying it could not
+ * identify the holder, rather than asserting the holder is not ours — a claim it has no evidence
+ * for, and one that was wrong for every Windows user.
+ */
+export declare function captureLookup(command: string, args: readonly string[]): string | null;
 /**
  * The FIRST listener in `lsof -nP -iTCP:<port> -sTCP:LISTEN -F pc` output, or null.
  *

package/dist/cli/port-holder.js

@@ -13,6 +13,27 @@
  * The parser is pure and the lookup takes an injected exec, so the rule is tested on every platform
  * while the shelling out stays at the call site.
  */
+import { spawnSync } from 'node:child_process';
+/** Bound on the holder lookup. A hung `lsof` must not hang the commands that diagnose hangs. */
+const LOOKUP_TIMEOUT_MS = 2_000;
+/**
+ * Run a lookup and return its stdout, or null if it could not run.
+ *
+ * Null on ANY failure — no lsof (every Windows user, a slim container), a non-zero exit, a throw.
+ * This is a diagnostic nicety inside the commands people run when things are already broken; it must
+ * never be the reason one of them fails. Every caller handles the null by saying it could not
+ * identify the holder, rather than asserting the holder is not ours — a claim it has no evidence
+ * for, and one that was wrong for every Windows user.
+ */
+export function captureLookup(command, args) {
+    try {
+        const result = spawnSync(command, [...args], { encoding: 'utf8', timeout: LOOKUP_TIMEOUT_MS });
+        return 0 === result.status && 'string' === typeof result.stdout ? result.stdout : null;
+    }
+    catch {
+        return null;
+    }
+}
 /** `lsof -F pc` emits one field per line, prefixed by its selector: `p<pid>`, `c<command>`. */
 const PID_FIELD = 'p';
 const COMMAND_FIELD = 'c';
@@ -59,8 +80,11 @@ export function describeForeignHolder(port, holder,
  * stranger, and the fix that works (`reticle stop`, it respawns on the next call) is never named.
  */
 ourPid) {
-    const tail = 'a daemon cannot bind it. Stop that process, or run Reticle on a different port ' +
-        '(`--port`), then retry.';
+    // Naming the command matters more than naming the process. "Stop that process" describes an
+    // outcome and leaves the reader to invent a route to it, and the route they invent is the `-ti`
+    // pipeline that takes their agent's proxy down with the holder.
+    const tail = 'a daemon cannot bind it. Free it with `reticle kill --force` (it signals the listener only, ' +
+        "never the agent's mcp proxy), or run Reticle on a different port (`--port`), then retry.";
     if (null === holder) {
         /**
          * We could not identify the holder — no `lsof` (every Windows user, and 35% of them by the

package/dist/cli.js

@@ -22,10 +22,12 @@ import { installDaemonResilience, installProxyResilience, recordExitReason, Daem
 import { IdleShutdown, resolveIdleShutdownMs, resolveIdleCheckMs } from './daemon/idle-shutdown.js';
 import { DaemonHeartbeat, resolveHeartbeatMs } from './daemon/heartbeat.js';
 import { everServedToolCall } from './daemon/daemon-usefulness.js';
-import { fetchStatus, summarizeStatus, warnOnDaemonSkew, decideOpen, openInBrowser, } from './cli/cli-launch.js';
+import { fetchStatus, summarizeStatus, warnOnDaemonSkew, decideOpen, drivePortConflict, openInBrowser, openCommand, } from './cli/cli-launch.js';
 import { handleVerify } from './cli/cli-verify.js';
+import { runKill } from './cli/cli-kill.js';
 import { summarizeHunt } from './hunt/hunt-report.js';
 import { runInit } from './init/run.js';
+import { confirmInstall, nodeConfirmDeps } from './init/confirm.js';
 import { handleDoctor } from './cli/cli-doctor.js';
 import { buildNodeIo } from './init/node-io.js';
 import { describeLicense } from './license/license.js';
@@ -38,6 +40,7 @@ import { reportCliRun } from './telemetry/cli-telemetry.js';
 export { parseCliArgs, CLI_USAGE };
 function handleInit(parsed) {
     const cwd = process.cwd();
+    const io = buildNodeIo(cwd);
     const result = runInit({
         cwd,
         port: parsed.port,
@@ -45,9 +48,14 @@ function handleInit(parsed) {
         dryRun: parsed.dryRun,
         install: parsed.install,
         ...(parsed.app === undefined ? {} : { app: parsed.app }),
-    }, buildNodeIo(cwd));
-    if (!result.ok)
-        process.exit(1);
+        // The outcome is reported by confirmInstall instead, once it knows whether an app connected —
+        // `init` writing files was never the same thing as `init` working (#269).
+        deferOutcome: true,
+    }, io);
+    void confirmInstall(result, io, nodeConfirmDeps(parsed.port ?? RETICLE_DEFAULT_PORT)).then(() => {
+        if (!result.ok)
+            process.exit(1);
+    });
 }
 function handleServe(parsed) {
     void serveWithHonestExit(parsed);
@@ -190,6 +198,28 @@ function handleStop(port, quiet) {
         }
     }, 100);
 }
+/**
+ * `reticle restart` — free the port, then put a daemon back on it and prove it bound.
+ *
+ * The two halves are reported separately on purpose. A restart that killed the old daemon and then
+ * could not start a new one leaves the user in a different place from one that could not kill
+ * anything at all, and a single `ok: false` cannot tell them which happened.
+ */
+async function handleRestart(port, force) {
+    const freed = await runKill(port, force);
+    if (!freed) {
+        log('reticle_restart_aborted', {
+            port,
+            reason: 'the port was not freed, so nothing was started — the old holder is still there',
+        });
+        process.exit(1);
+        return;
+    }
+    // Reuses `serve`'s path, which waits for the daemon to ANSWER before claiming it started and exits
+    // non-zero when it does not. A restart that reports success for a daemon that never bound is the
+    // same lie `serve` already stopped telling.
+    await serveWithHonestExit({ port, headless: true, http: false });
+}
 function handleStatus(port) {
     const pid = readPid(port);
     if (null === pid || !isAlive(pid)) {
@@ -364,8 +394,12 @@ function handleOpen(requestedPort, url) {
             log('reticle_open', {
                 port,
                 error: `could not launch a browser: ${launchError}`,
-                recovery: 'Open the url yourself, or run `reticle doctor` — it checks the pieces this command ' +
-                    'depends on.',
+                // Points at the OS handler, not at `reticle doctor`. Doctor's browser check is about
+                // Reticle's own Chromium, which this command never touches — the same misdirect the
+                // no-session note below spells out at length, left standing here for one more release.
+                recovery: 'Nothing was opened. This command asks the OS to open a url in your default browser ' +
+                    `(\`${openCommand(decision.url, process.platform).cmd}\` on this platform) and that ` +
+                    'failed, so the fix is on the OS side: open the url yourself, or set a default browser.',
             });
             process.exit(1);
             return;
@@ -560,8 +594,13 @@ function handleMcp(opts) {
                 daemonArgs.push(HTTP_TOKEN_FLAG, httpToken);
         }
         spawnDaemon(process.execPath, scriptPath, daemonArgs, port);
-        log('reticle_mcp_daemon_started', { port, ...(driveUrl !== undefined ? { driveUrl } : {}) });
+        // Announce the daemon only once the PORT ACCEPTS. This line used to be written the instant the
+        // child was spawned, which on a Windows first bootstrap meant `reticle_mcp_daemon_started`
+        // followed about ten seconds later by `reticle_mcp_daemon_unavailable` and a first
+        // `reticle_sessions` that expired. A readiness signal that precedes readiness is worse than
+        // none: a client that believes it stops waiting for the thing that has not happened.
         await waitForDaemon(port);
+        log('reticle_mcp_daemon_started', { port, ...(driveUrl !== undefined ? { driveUrl } : {}) });
     };
     // Start the proxy WHATEVER happened to the daemon.
     //
@@ -602,20 +641,57 @@ function handleMcp(opts) {
     });
 }
 function handleLegacyDrive(parsed) {
+    void driveWithHonestConflict(parsed);
+}
+/**
+ * Refuse the port BEFORE binding it, and name what is holding it.
+ *
+ * `drive` went straight to `start`, which binds. The listen error surfaces asynchronously on the
+ * server object long after `start` has resolved, so the `.catch` on that promise could never see it
+ * and the process died with the raw `node:net` EADDRINUSE stack — in the one situation this command
+ * is most often run in, since `reticle_sessions` recommends `reticle drive` for a throttled tab and
+ * a throttled tab nearly always coexists with the daemon holding the port.
+ */
+async function driveWithHonestConflict(parsed) {
+    const presence = await probePresence(parsed.port, { tcpOpen: probeDaemon, status: fetchStatus });
+    const conflict = drivePortConflict(presence, parsed.port, { ourPid: readPid(parsed.port) });
+    if (conflict !== undefined) {
+        log('reticle_drive_port_conflict', { port: parsed.port, presence, reason: conflict });
+        process.stderr.write(`${conflict}\n`);
+        process.exit(1);
+        return;
+    }
+    // The probe cannot close the race: something can take the port between here and the bind, and the
+    // bind reports it on the server, outside every promise this function holds. Catching it at the
+    // process is the only place that sees it at all — and only EADDRINUSE, so a genuine crash still
+    // crashes rather than being dressed up as a port conflict. Who won the race is not knowable from
+    // in here, so the sentence used is the one that is true of any holder.
+    process.on('uncaughtException', (error) => {
+        const code = error?.code;
+        if ('EADDRINUSE' !== code)
+            throw error;
+        const reason = drivePortConflict(PortPresence.FOREIGN, parsed.port);
+        log('reticle_drive_port_conflict', {
+            port: parsed.port,
+            presence: PortPresence.FOREIGN,
+            reason,
+        });
+        process.stderr.write(`${String(reason)}\n`);
+        process.exit(1);
+    });
     const options = {
         port: parsed.port,
         driveUrl: parsed.driveUrl,
         headless: parsed.headless,
     };
-    start(options)
-        .then(() => {
+    try {
+        await start(options);
         log('reticle_started', { port: parsed.port });
-    })
-        .catch((error) => {
-        const message = error instanceof Error ? error.message : String(error);
-        log('reticle_start_failed', { error: message });
+    }
+    catch (error) {
+        log('reticle_start_failed', { error: error instanceof Error ? error.message : String(error) });
         process.exit(1);
-    });
+    }
 }
 function main() {
     // Before anything reads process.env — notably the telemetry gate and the bridge's security
@@ -669,6 +745,15 @@ function main() {
         case 'stop':
             handleStop(parsed.port, parsed.quiet);
             break;
+        case 'kill':
+            void runKill(parsed.port, parsed.force).then((freed) => {
+                if (!freed)
+                    process.exit(1);
+            });
+            break;
+        case 'restart':
+            void handleRestart(parsed.port, parsed.force);
+            break;
         case 'status':
             handleStatus(parsed.port);
             break;

package/dist/crawl/crawl-tools.js

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { ReticleTool } from '../tools/tool-names.js';
 import { asNumber, asString } from '../tools/tools-helpers.js';
 import { crawl } from './crawl.js';
+import { routeFromUrl, routesFromEvents } from '../project/learned-routes.js';
 const nodeSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /**
  * The autonomous "smart monkey" tool. Builds on reticle_explore (which only LISTS) by
@@ -58,8 +59,10 @@ export const CRAWL_TOOLS = [
                 .describe('Present only when the page exceeded one snapshot, so controls past the cap were never listed. When present, a zero-anomaly result does NOT mean the app is clean.'),
             truncated: z.boolean(),
         },
-        handler: (deps, args) => {
+        handler: async (deps, args) => {
             const session = deps.sessions.resolve(asString(args['sessionId']));
+            const since = session.elapsed();
+            const initialRoute = routeFromUrl(session.url);
             const maxSteps = asNumber(args['maxSteps']);
             const settleMs = asNumber(args['settleMs']);
             const scope = asString(args['scope']);
@@ -69,7 +72,14 @@ export const CRAWL_TOOLS = [
                 ...(scope !== undefined ? { scope } : {}),
                 ...(true === args['confirmDangerous'] ? { confirmDangerous: true } : {}),
             };
-            return crawl(session, opts, nodeSleep);
+            const report = await crawl(session, opts, nodeSleep);
+            const routes = [
+                ...(initialRoute === undefined ? [] : [initialRoute]),
+                ...routesFromEvents(session.eventsSince(since)),
+            ];
+            if (routes.length > 0)
+                await deps.project.recordRoutes(routes);
+            return report;
         },
     },
 ];

package/dist/crawl/crawl.d.ts

@@ -39,6 +39,19 @@ 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

@@ -6,6 +6,23 @@ import { ReticleTool } from '../tools/tool-names.js';
 import { findContradictions } from '../events/contradictions.js';
 /** Said out loud when the page was larger than one snapshot, so a clean sweep cannot mean "all clear". */
 export const CAPPED_SNAPSHOT_NOTE = 'the page exceeded one snapshot, so controls past the cap were never seen — 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 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');
+}
 /** Any buffer event that proves the app reacted to a click (vs a dead/no-op control). */
 function isActivity(e) {
     return (e.type === EventType.NET_REQUEST ||
@@ -50,6 +67,25 @@ export function legitimatelyInert(desc) {
         return true;
     return /\b(textbox|searchbox|combobox|spinbutton)\b/.test(desc);
 }
+/**
+ * How many interactive controls exist now that did not exist when the crawl enumerated.
+ *
+ * Keyed on ref, which is the element's identity: a control that re-rendered keeps its ref and is not
+ * new, and one that vanished simply does not appear. Returns 0 rather than throwing if the snapshot
+ * fails — this is a disclosure, and failing the whole crawl to report on coverage would be worse
+ * than the silence it is fixing.
+ */
+async function countRevealed(session, opts, before) {
+    const snap = await session.command(ReticleCommand.SNAPSHOT, {
+        mode: 'interactive',
+        ...(opts.scope !== undefined ? { scope: opts.scope } : {}),
+    });
+    if (!snap.ok)
+        return 0;
+    const tree = (snap.result ?? {}).tree ?? '';
+    const known = new Set(before.map((i) => (i.ref !== '' ? i.ref : i.desc)));
+    return parseInteractive(tree).filter((i) => !known.has(i.ref !== '' ? i.ref : i.desc)).length;
+}
 export async function crawl(session, opts, sleep) {
     const maxSteps = opts.maxSteps ?? CRAWL_DEFAULTS.MAX_STEPS;
     const settleMs = opts.settleMs ?? CRAWL_DEFAULTS.SETTLE_MS;
@@ -168,6 +204,14 @@ export async function crawl(session, opts, sleep) {
             });
         }
     }
+    // One more look, AFTER the clicks. The enumeration above happened before any of them, so anything
+    // the crawl itself unlocked — a dashboard behind a login, a modal's contents, a tab's panel — was
+    // never in `items` and never had a chance to be visited. Counted by ref against what was
+    // enumerated, so a control that merely moved or re-rendered under the same ref is not miscounted
+    // as new, and a surface that SHRANK (a modal closed) reports nothing, because nothing went
+    // unvisited. Skipped when the snapshot was already capped: that case has its own note and a second
+    // one would only muddy it.
+    const revealed = coverageCapped ? 0 : await countRevealed(session, opts, items);
     return {
         interactiveFound: items.length,
         stepsRun,
@@ -177,8 +221,12 @@ export async function crawl(session, opts, sleep) {
         // True when coverage was bounded for EITHER reason: the step budget ran out, or the page was
         // bigger than one snapshot. Conflating "I stopped early" with "I saw everything" is what turns a
         // partial sweep into "all controls healthy".
-        truncated: items.length > stepsRun || coverageCapped,
-        ...(coverageCapped ? { coverageNote: CAPPED_SNAPSHOT_NOTE } : {}),
+        truncated: items.length > stepsRun || coverageCapped || revealed > 0,
+        ...(coverageCapped
+            ? { coverageNote: CAPPED_SNAPSHOT_NOTE }
+            : revealed > 0
+                ? { coverageNote: revealedControlsNote(revealed) }
+                : {}),
         // A bare `stepsRun: 0` made "the page had no controls" and "it had 34 and none were clicked" the
         // same answer. See crawl-empty.
         ...(() => {

package/dist/events/contradictions.d.ts

@@ -35,6 +35,20 @@ export interface ContradictionOptions {
      * contain. See `findUnitMismatches` for the measured case this exists for.
      */
     prior?: readonly ReticleEvent[] | undefined;
+    /**
+     * Event time at which the action that opened this window was dispatched — the attribution floor.
+     *
+     * `duplicate-request` claims "one user action was performed", and that claim is only sound over ONE
+     * action's window. `reticle_observe` takes a caller-supplied window that can be arbitrarily wide, so
+     * two legitimate separate saves to the same endpoint read as a double submit — and the finding then
+     * sat on every verdict for that tab. Undefined means nothing attributed the window to an action, and
+     * the rule stays silent rather than accusing an app of something nobody can show it did.
+     *
+     * ponytail: a NET_REQUEST is stamped when it COMPLETED, so a write dispatched before the action and
+     * landing after it counts as inside. Keying on the matching NET_PENDING would fix that; it has not
+     * been worth the second index.
+     */
+    actionSince?: number | undefined;
     /**
      * DOM mutations observed INSIDE the target's own subtree, as the act tool measured them.
      *

package/dist/events/contradictions.js

@@ -281,23 +281,32 @@ export function findContradictions(allEvents, options = {}) {
             });
         }
     }
-    // ── The same write fired more than once ─────────────────────────────────────────────────────
-    const writeCounts = new Map();
-    for (const call of settled) {
-        if (!isMutating(call))
-            continue;
-        const key = `${call.method} ${call.url}`;
-        writeCounts.set(key, (writeCounts.get(key) ?? 0) + 1);
-    }
-    for (const [key, 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)}`,
-        });
+    // ── 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.
+    const actionSince = options.actionSince;
+    if (actionSince !== undefined) {
+        const writeCounts = new Map();
+        for (const event of events) {
+            if (event.type !== EventType.NET_REQUEST || event.t < actionSince)
+                continue;
+            const call = netCall(event);
+            if (!isMutating(call))
+                continue;
+            const key = `${call.method} ${call.url}`;
+            writeCounts.set(key, (writeCounts.get(key) ?? 0) + 1);
+        }
+        for (const [key, 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)}`,
+            });
+        }
     }
     // ── The UI advanced over a request that never came back ─────────────────────────────────────
     // Gated on the UI having moved: an in-flight request while the app is still visibly waiting is

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

@@ -1,4 +1,4 @@
-import { ElementState, PredicateKind, type ElementQuery, type ReticleEvent } from '@reticlehq/core';
+import { ElementState, PredicateKind, type ElementDescriptor, type ElementQuery, type ReticleEvent } from '@reticlehq/core';
 import { z } from 'zod';
 export type Predicate = {
     kind: typeof PredicateKind.ELEMENT;
@@ -58,6 +58,25 @@ export type Predicate = {
     kind: typeof PredicateKind.NOT;
     predicate: Predicate;
 };
+export interface ResidualQueryChecks {
+    /** Dropped fields this side CAN check, as [field, wanted value] pairs. */
+    checks: [string, string][];
+    /** Dropped fields with no descriptor to check them against — refuse rather than ignore. */
+    unusable: string[];
+}
+/**
+ * Split a query's dropped fields into the ones the server can still enforce and the ones it cannot.
+ *
+ * The alternative — refuse every dropped field — breaks calls that work today and that our own
+ * cheatsheet advertises (`{ role: "button", text: "Save" }`), and breaks them into no verdict at all.
+ * Enforcing what we can and refusing only the rest keeps those calls working AS WRITTEN, which is the
+ * outcome the caller was already assuming.
+ */
+export declare function residualQueryChecks(query: ElementQuery): ResidualQueryChecks;
+/** Does this element satisfy every field the locator dropped? */
+export declare function satisfiesResiduals(element: ElementDescriptor, checks: readonly [string, string][]): boolean;
+/** How the element's own reading of a dropped field should be REPORTED back on a failure. */
+export declare function describeResidual(element: ElementDescriptor, field: string): string;
 export declare const PredicateSchema: z.ZodType<Predicate>;
 /**
  * The fields a given predicate kind accepts, read off the schema itself.